# Add a document to a signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/add-a-document-to-a-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json post /signing-requests/{id}/documents
Adds a document (a temporary upload from `POST /documents`) to the signing request's document set, at `position` or last. Documents at that position and after it move up by one. At most 20 documents and 100 MB per signing request. A sent, finished, cancelled or declined signing request answers `409 DOCUMENT_SET_LOCKED`.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Cancel a signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/cancel-a-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json post /signing-requests/{id}/cancel
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.



# Comprehensive Update Signing Request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/comprehensive-update-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json put /signing-requests/{id}
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.



# Create and Send Signing Request (Atomic)
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/create-and-send-signing-request-atomic

api-reference/v01.40.04/openapi-v01.40.04.json post /signing-requests/create-and-send
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
- If the send step fails before any part of the send has started, the signing request is removed and an error is returned: the send step's `400`, `402` or `422`, some `409` codes, otherwise `500`. No draft is left behind
- If the send had already started, the request is kept and the response is a `409` carrying its `signing_request_id`: code `SEND_EFFECTS_EXIST`, or `ALREADY_SENT` if the send completed. Recover that request instead of retrying the create. A `409` with code `SEND_IN_PROGRESS` also leaves the request in place

**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)



# Create Signing Request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/create-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json post /signing-requests
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.



# Delete a signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/delete-a-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json delete /signing-requests/{id}
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.



# Download one document of a signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/download-one-document-of-a-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/documents/{document_id}/download
`type=original` (the default): a signed URL to the document as uploaded (`404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when it is no longer stored). `type=document`: a signed URL to the individually sealed document, available once the certificate is bound (`404 DOCUMENT_SIGNED_NOT_AVAILABLE` before). The URL is valid for 1 hour.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation remains available for parents on the multi-document read-only path; parents on the single-document path answer `404 NOT_FOUND`.



# Download Signing Request Document
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/download-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/download
Retrieve a download URL for a signing request's signed document. For a completed signing request, returns the final signed PDF with the completion certificate. For a sent signing request that is not completed (in progress, expired, cancelled or declined), returns a URL to a partial-progress snapshot of the signers who have completed so far.

**Partial downloads:** Available for every sent signing request that is not completed; there is no setting to enable. If the snapshot is still being generated, 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`.



# Get Signing Request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/get-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}
Retrieve a specific signing request by ID



# Get signing request fields
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/get-signing-request-fields

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/fields
Retrieve all fields for a specific signing request with their values



# Get signing request users
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/get-signing-request-users

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/users
Retrieve all recipients/users for a specific signing request



# List Signing Requests
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/list-signing-requests

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests
Retrieve a paginated list of signing requests



# Partially Update Signing Request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/partially-update-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json patch /signing-requests/{id}
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, except for a seal swap (see `seal_participant`). A `seal_participant` that names a seal answers 404 `NOT_FOUND` when the seal does not exist or belongs to another company, and 400 `SEAL_UNAVAILABLE` when the seal is revoked, deleted or not the current version of its lineage, and also when it is limited to a workspace other than the signing request's. These answers are for adding a seal participant and for changing its seal. A seal swap (`swap_to_seal_id`) answers differently for the new seal: 404 `NOT_FOUND` when it does not exist, belongs to another company or is limited to a workspace other than the signing request's; 409 `SEAL_UNAVAILABLE` when it is revoked, deleted or not the current version of its lineage; 400 `SEAL_FIELD_REQUIRED` when the seal participant has no stamp field on the signing request. Adding a seal participant or changing its seal answers 503 `SEALS_DISABLED` when organization seals are not enabled. Adding a seal participant requires `order` (see the order contract). A field that belongs to a seal participant accepts only `position` and `page_number` changes; every other key of `field`, `recipient_id` included, is ignored.



# Remove a document from a signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/remove-a-document-from-a-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json delete /signing-requests/{id}/documents/{document_id}
Removes a document from the signing request. The last remaining document cannot be removed (`400 MIN_DOCUMENTS_REQUIRED`). A sent, finished, cancelled or declined signing request answers `409 DOCUMENT_SET_LOCKED`.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Reorder a signing request's documents
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/reorder-a-signing-requests-documents

api-reference/v01.40.04/openapi-v01.40.04.json put /signing-requests/{id}/documents/order
Sets the order of the signing request's documents. `document_ids` must name every document of the signing request exactly once: a missing or repeated id answers `400 INVALID_DOCUMENT_ORDER`, an id that is not a document of this signing request `404 DOCUMENT_NOT_FOUND`. A sent, finished, cancelled or declined signing request answers `409 DOCUMENT_SET_LOCKED`.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Replace or rename a signing request document
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/replace-or-rename-a-signing-request-document

api-reference/v01.40.04/openapi-v01.40.04.json patch /signing-requests/{id}/documents/{document_id}
Send exactly one of `document_id` (replace the document with a temporary upload from `POST /documents`: the same number of pages, every page the same size within 1 pt) or `label` (rename). Both, or neither, answers `400 VALIDATION_ERROR`. A document placed with anchor tags is replaced only when the anchors of the replacement resolve exactly as stored; otherwise `400 ANCHOR_MISMATCH`. A sent, finished, cancelled or declined signing request answers `409 DOCUMENT_SET_LOCKED`.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Resend signing request to specific recipients
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/resend-signing-request-to-specific-recipients

api-reference/v01.40.04/openapi-v01.40.04.json post /signing-requests/{id}/resend
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.



# Retrieve Signer-Uploaded File
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/retrieve-signer-file

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/signers/{signer_id}/files/{field_id}
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.



# Retrieve Signer Initials Image
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/retrieve-signer-initials

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/signers/{signer_id}/initials
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.



# Retrieve Signer Signature Image
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/retrieve-signer-signature

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/signers/{signer_id}/signature
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 `<img src>`. 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.



# Retrieve Signer Stamp Image
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/retrieve-signer-stamp

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}
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.



# Send signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/send-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json post /signing-requests/{id}/send
Send a signing request to all recipients via email. This triggers email delivery and sets the sent_on timestamp.



# Upload a document
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/upload-document

api-reference/v01.40.04/openapi-v01.40.04.json post /documents
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.



# Add a document to a template
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/add-a-document-to-a-template

api-reference/v01.40.04/openapi-v01.40.04.json post /templates/{id}/documents
Adds a document (a temporary upload from `POST /documents`) to the template's document set, at `position` or last. Documents at that position and after it move up by one. At most 20 documents and 100 MB per template.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Comprehensive Template Update
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/comprehensive-template-update

api-reference/v01.40.04/openapi-v01.40.04.json put /templates/{id}
Comprehensive update of template including properties, users, fields, and reminders. Supports user deletion with field reassignment or deletion. All sections are optional but at least one must be provided.

**Not atomic.** The parts of this call are not applied as one update. Each entry of `users` or `deleted_users` that adds, moves or removes a signer or an approver is saved on its own, in the order of the request. If one of these saves is refused, the call answers at once with that error: what was saved before it stays applied and the rest of the request is not processed. Other problems (for example a user that is not found, or an invalid field or reminder) are collected and answered as one 400 `VALIDATION_ERROR` at the end of the call. Once a problem was collected, some of the remaining changes are skipped (the `users`, `fields` and `reminders` entries that follow it) and others can still be applied before the 400, and what was saved before the problem stays applied. The 400 does not always say which entries failed. Read the template again after any non-2xx response. If the read of the template's seal participants for the response fails after the writes, the call answers 500 although the writes were applied.

**Seal participants.** The request property `seal_participants` sets the seal participants of the template. When the key is absent, the seal participants of the template are left unchanged. When it is an array, the array replaces the whole set: every seal participant the template had is removed together with the fields it owned, and one seal participant is created for each entry, so `[]` removes them all. Each entry is an object with `seal_id` (required, the ID of an organization seal), `order` (required, a positive integer that no other entry repeats and that is not greater than the number of recipients of the template plus the number of entries) and an optional `temp_id`. The recipients keep their relative order and each seal is placed at its `order`. `null`, any other value that is not an array and an entry without `seal_id` answer 400 `VALIDATION_ERROR`; an `order` that breaks the rules above answers 400 `INVALID_SIGNING_ORDER`; a `seal_id` that is not a UUID answers 404 `NOT_FOUND`; a seal of your company that is revoked or deleted answers 400 `SEAL_UNAVAILABLE`. Each of these answers is immediate and leaves the seal participants unchanged. `seal_participants` is processed after the other parts of the call, also when they collected problems, so it can be applied in a call that then answers 400 `VALIDATION_ERROR`.



# Copy template to another workspace
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/copy-template-to-workspace

api-reference/v01.40.04/openapi-v01.40.04.json post /templates/{id}/copy
Deep-copies a template (including fields, recipients, CC, reminders, custom field definitions, and the PDF document) to a target workspace within the same company. Requires a company-level (protected) API key. Multi-document (available to every company): the copy of a template with more than one document is a template with ONE document, the merged document of the source; its content and the absolute page numbers of its fields are kept, the per-document labels and positions are not carried. While multi-document editing is suspended, copying a template on the multi-document read-only path answers `409 MULTI_DOCUMENT_READ_ONLY`; other templates use the single-document path.



# Create Template
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/create-template

api-reference/v01.40.04/openapi-v01.40.04.json post /templates
Create a new template with a base64-encoded PDF document. The API automatically extracts the page count from the document.

`seal_participants`, `recipients` and `fields` are not accepted keys on this operation: they are ignored and nothing is created from them. When the request body contains any of them (the key being present is enough, whatever its value, including `null` or `[]`), the 201 response carries `warnings`, one string per ignored key. Add participants and fields with `PATCH /templates/{id}` or `PUT /templates/{id}`.



# Delete a template
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/delete-a-template

api-reference/v01.40.04/openapi-v01.40.04.json delete /templates/{id}
Soft delete a template by ID. This marks the template as deleted but retains the data.



# Duplicate template into signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/duplicate-template-into-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json post /templates/{id}/duplicate
Creates a new signing request by duplicating an existing template, including all fields, users, reminders, and settings.

**Seals.** The new signing request carries the template's seal participants and the template fields that belong to them. This operation takes no `seal_participants` key. While multi-document editing is suspended, templates on the multi-document read-only path answer 409 `MULTI_DOCUMENT_READ_ONLY`. For templates on the single-document path during that suspension, a template seal follows the current version of its lineage: if that current version is revoked or deleted, or the lineage has no current version, the call answers 409 `SEAL_UNAVAILABLE` and creates nothing; a seal that the API key's company cannot see, or that is limited to a workspace other than the target workspace, is not copied and neither are its fields, and the 201 lists it in `seal_participants` as a dropped entry; if a seal would be kept while organization seals are not enabled, the call answers 503 `SEALS_DISABLED`; the 201 always carries `seal_participants` (an empty array when the template has no seal participants). For every company during normal operation, the copy attaches the template's stored seal version as it is, the 201 does not carry `seal_participants`, and a seal that was replaced, revoked or deleted since the template was saved fails when the request is sent.



# Get Template
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/get-template

api-reference/v01.40.04/openapi-v01.40.04.json get /templates/{id}
Retrieve a specific template by ID. The response includes `seal_participants`: the template's seal participants in order, limited to those whose seal belongs to the company of the API key. A seal participant whose seal is missing or belongs to another company is omitted, so an empty or shorter list does not prove that the template has no other seal participant stored.



# Get template fields
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/get-template-fields

api-reference/v01.40.04/openapi-v01.40.04.json get /templates/{id}/fields
Retrieve all fields configured for a specific template



# Get template reminders
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/get-template-reminders

api-reference/v01.40.04/openapi-v01.40.04.json get /templates/{id}/reminders
Retrieve all reminders configured for a specific template



# Get template users
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/get-template-users

api-reference/v01.40.04/openapi-v01.40.04.json get /templates/{id}/users
Retrieve all recipients/users associated with a specific template



# List Templates
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/list-templates

api-reference/v01.40.04/openapi-v01.40.04.json get /templates
Retrieve a paginated list of templates



# Partially Update Template
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/partially-update-template

api-reference/v01.40.04/openapi-v01.40.04.json patch /templates/{id}
Update template properties, a single user, OR a single field. Cannot mix multiple entity types in one request. Use PUT for comprehensive updates including users, fields, and reminders. A `seal_participant` that names a seal answers 404 `NOT_FOUND` when the seal does not exist or belongs to another company, and 400 `SEAL_UNAVAILABLE` when the seal is revoked, deleted or not the current version of its lineage. Adding a seal participant or changing its seal answers 503 `SEALS_DISABLED` when organization seals are not enabled. Adding a seal participant requires `order` (see the order contract).



# Remove a document from a template
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/remove-a-document-from-a-template

api-reference/v01.40.04/openapi-v01.40.04.json delete /templates/{id}/documents/{document_id}
Removes a document from the template. The last remaining document cannot be removed (`400 MIN_DOCUMENTS_REQUIRED`).

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Reorder a template's documents
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/reorder-a-templates-documents

api-reference/v01.40.04/openapi-v01.40.04.json put /templates/{id}/documents/order
Sets the order of the template's documents. `document_ids` must name every document of the template exactly once: a missing or repeated id answers `400 INVALID_DOCUMENT_ORDER`, an id that is not a document of this template `404 DOCUMENT_NOT_FOUND`.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Replace or rename a template document
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/replace-or-rename-a-template-document

api-reference/v01.40.04/openapi-v01.40.04.json patch /templates/{id}/documents/{document_id}
Send exactly one of `document_id` (replace the document with a temporary upload from `POST /documents`: the same number of pages, every page the same size within 1 pt) or `label` (rename). Both, or neither, answers `400 VALIDATION_ERROR`.

**Available to every company.** This operation is part of the multi-document contract (API 01.39.00). For a signing request or template the API key cannot see, it answers `404` with code `NOT_FOUND` ("Endpoint not found"), exactly as an unknown endpoint does. While multi-document editing is suspended, this operation returns `409 MULTI_DOCUMENT_READ_ONLY` for parents on the multi-document read-only path and `404 NOT_FOUND` for parents on the single-document path.



# Replace template document
Source: https://docs.firma.dev/api-reference/v01.40.04/templates/replace-template-document

api-reference/v01.40.04/openapi-v01.40.04.json post /templates/{id}/replace-document
Replaces the PDF document of an existing template while preserving all field placements. The replacement document must have the same page count and matching page dimensions (within 1pt tolerance) as the original.



# Create a new workspace
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/create-a-new-workspace

api-reference/v01.40.04/openapi-v01.40.04.json post /workspaces
Create a new workspace for the authenticated company. All workspaces are created as non-protected by default. The protected status can only be set during company account creation.



# Expire pending API keys
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/expire-pending-api-keys

api-reference/v01.40.04/openapi-v01.40.04.json post /workspaces/{id}/api-key/expire
Immediately expires all pending API keys (those with expires_at set) for a workspace. Useful after verifying that the new key works correctly. Cannot be used on protected workspaces. Rate limited to 1 request per minute.



# Get a workspace
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/get-a-workspace

api-reference/v01.40.04/openapi-v01.40.04.json get /workspaces/{id}
Retrieve a specific workspace by ID including its API key



# List workspaces
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/list-workspaces

api-reference/v01.40.04/openapi-v01.40.04.json get /workspaces
Retrieve a paginated list of workspaces for the authenticated company



# Partially update a workspace
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/partially-update-a-workspace

api-reference/v01.40.04/openapi-v01.40.04.json patch /workspaces/{id}
Update specific workspace fields. Only the name can be updated via API. The protected field is read-only and can only be set during company account creation.



# Regenerate workspace API key
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/regenerate-workspace-api-key

api-reference/v01.40.04/openapi-v01.40.04.json post /workspaces/{id}/api-key/regenerate
Regenerates the API key for a workspace. Sets 24-hour expiration on existing active keys and creates a new key. Cannot be used on protected workspaces. Rate limited to 1 request per minute.



# Remove Workspace Logo
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/remove-workspace-logo

api-reference/v01.40.04/openapi-v01.40.04.json delete /workspaces/{id}/logo
Remove the workspace logo. Certificates will fall back to the company logo, or the Firma default.



# Update a workspace
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/update-a-workspace

api-reference/v01.40.04/openapi-v01.40.04.json put /workspaces/{id}
Update an existing workspace's information. This is a full replacement operation requiring the name field.



# Upload Workspace Logo
Source: https://docs.firma.dev/api-reference/v01.40.04/workspaces/upload-workspace-logo

api-reference/v01.40.04/openapi-v01.40.04.json post /workspaces/{id}/logo
Upload a logo for a specific workspace. Overrides the company logo on certificates and emails for this workspace. Accepts PNG or JPEG, max 2MB.



# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Get company information
Source: https://docs.firma.dev/api-reference/v01.40.04/company/get-company-information

api-reference/v01.40.04/openapi-v01.40.04.json get /company
Retrieve information about the authenticated company



# Get company settings
Source: https://docs.firma.dev/api-reference/v01.40.04/company/get-company-settings

api-reference/v01.40.04/openapi-v01.40.04.json get /company/settings
Retrieve settings for the authenticated company



# Partially update company information
Source: https://docs.firma.dev/api-reference/v01.40.04/company/partially-update-company-information

api-reference/v01.40.04/openapi-v01.40.04.json patch /company
Update specific company fields. Only provided fields will be updated. At least one field must be provided.



# Remove Company Logo
Source: https://docs.firma.dev/api-reference/v01.40.04/company/remove-company-logo

api-reference/v01.40.04/openapi-v01.40.04.json delete /company/logo
Remove the company logo. Certificates will use the Firma default logo.



# Update company information
Source: https://docs.firma.dev/api-reference/v01.40.04/company/update-company-information

api-reference/v01.40.04/openapi-v01.40.04.json put /company
Update all company details. This is a full replacement operation requiring all fields except icon_url.



# Update company settings
Source: https://docs.firma.dev/api-reference/v01.40.04/company/update-company-settings

api-reference/v01.40.04/openapi-v01.40.04.json put /company/settings
Update company settings. Only provided fields will be updated.



# Upload Company Logo
Source: https://docs.firma.dev/api-reference/v01.40.04/company/upload-company-logo

api-reference/v01.40.04/openapi-v01.40.04.json post /company/logo
Upload a logo image for the company. Accepts PNG or JPEG, max 2MB. Replaces any existing logo.



# Create signing request custom field
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/create-signing-request-custom-field

api-reference/v01.40.04/openapi-v01.40.04.json post /signing-requests/{request_id}/custom-fields
Create a new custom field definition for a signing request



# Create template custom field
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/create-template-custom-field

api-reference/v01.40.04/openapi-v01.40.04.json post /templates/{template_id}/custom-fields
Create a new custom field definition for a template



# Create workspace custom field
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/create-workspace-custom-field

api-reference/v01.40.04/openapi-v01.40.04.json post /workspace/{workspace_id}/custom-fields
Create a new custom field definition for a workspace



# Delete signing request custom field
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/delete-signing-request-custom-field

api-reference/v01.40.04/openapi-v01.40.04.json delete /signing-requests/{request_id}/custom-fields/{field_id}
Soft-delete a custom field definition from a signing request



# Delete template custom field
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/delete-template-custom-field

api-reference/v01.40.04/openapi-v01.40.04.json delete /templates/{template_id}/custom-fields/{field_id}
Soft-delete a custom field definition from a template



# Delete workspace custom field
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/delete-workspace-custom-field

api-reference/v01.40.04/openapi-v01.40.04.json delete /workspace/{workspace_id}/custom-fields/{field_id}
Soft-delete a custom field definition



# List signing request custom fields
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/list-signing-request-custom-fields

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{request_id}/custom-fields
Get all custom field definitions for a signing request



# List template custom fields
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/list-template-custom-fields

api-reference/v01.40.04/openapi-v01.40.04.json get /templates/{template_id}/custom-fields
Get all custom field definitions for a template



# List workspace custom fields
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/list-workspace-custom-fields

api-reference/v01.40.04/openapi-v01.40.04.json get /workspace/{workspace_id}/custom-fields
Get all custom field definitions for a workspace



# Update workspace custom field
Source: https://docs.firma.dev/api-reference/v01.40.04/custom-fields/update-workspace-custom-field

api-reference/v01.40.04/openapi-v01.40.04.json put /workspace/{workspace_id}/custom-fields/{field_id}
Update an existing custom field definition



# Add company domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/add-company-domain

api-reference/v01.40.04/openapi-v01.40.04.json post /company/domains
Add a new email domain for the company. This initiates the domain verification process. After creation, you must:
1. Add a TXT record to your DNS with the verification token
2. Call POST /company/domains/{id}/verify-ownership to verify domain ownership
3. Call POST /company/domains/{id}/finalize to register with email provider
4. Add the returned DNS records (SPF, DKIM, etc.)
5. Call POST /company/domains/{id}/verify-dns to complete verification



# Add workspace domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/add-workspace-domain

api-reference/v01.40.04/openapi-v01.40.04.json post /workspace/{workspace_id}/domains
Add a new email domain for a specific workspace. This initiates the domain verification process. After creation, you must:
1. Add a TXT record to your DNS with the verification token
2. Call POST /workspace/{workspace_id}/domains/{id}/verify-ownership to verify domain ownership
3. Call POST /workspace/{workspace_id}/domains/{id}/finalize to register with email provider
4. Add the returned DNS records (SPF, DKIM, etc.)
5. Call POST /workspace/{workspace_id}/domains/{id}/verify-dns to complete verification



# Delete company domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/delete-company-domain

api-reference/v01.40.04/openapi-v01.40.04.json delete /company/domains/{id}
Remove a domain from the company. If the domain is the primary or only domain, sending reverts to the company or default sender.



# Delete workspace domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/delete-workspace-domain

api-reference/v01.40.04/openapi-v01.40.04.json delete /workspace/{workspace_id}/domains/{id}
Remove a domain from the workspace. If the domain is the primary or only domain, sending reverts to the company or default sender.



# Finalize domain setup
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/finalize-domain-setup

api-reference/v01.40.04/openapi-v01.40.04.json post /company/domains/{id}/finalize
Finalize domain setup by registering with the email provider. This returns the DNS records (SPF, DKIM, DMARC) that must be added to enable email sending. Can only be called after domain ownership is verified.



# Finalize workspace domain setup
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/finalize-workspace-domain-setup

api-reference/v01.40.04/openapi-v01.40.04.json post /workspace/{workspace_id}/domains/{id}/finalize
Finalize domain setup by registering with the email provider. This returns the DNS records (SPF, DKIM, DMARC) that must be added to enable email sending. Can only be called after domain ownership is verified.



# Get company domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/get-company-domain

api-reference/v01.40.04/openapi-v01.40.04.json get /company/domains/{id}
Retrieve details of a specific company domain including verification status and DNS records



# Get workspace domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/get-workspace-domain

api-reference/v01.40.04/openapi-v01.40.04.json get /workspace/{workspace_id}/domains/{id}
Retrieve details of a specific domain in a workspace including verification status and DNS records



# List company domains
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/list-company-domains

api-reference/v01.40.04/openapi-v01.40.04.json get /company/domains
List all email domains configured for the company (domains on the protected/default workspace). These domains are used as the default sending domain for all workspaces.



# List workspace domains
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/list-workspace-domains

api-reference/v01.40.04/openapi-v01.40.04.json get /workspace/{workspace_id}/domains
List all email domains configured for a specific workspace. These domains are used for sending signing request emails from this workspace.



# Set primary domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/set-primary-domain

api-reference/v01.40.04/openapi-v01.40.04.json post /company/domains/{id}/set-primary
Set a domain as the primary sending domain for the company. Only fully verified domains (domain_status=1) can be set as primary.



# Set primary workspace domain
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/set-primary-workspace-domain

api-reference/v01.40.04/openapi-v01.40.04.json post /workspace/{workspace_id}/domains/{id}/set-primary
Set a domain as the primary sending domain for the workspace. Only fully verified domains (domain_status=1) can be set as primary.



# Verify DNS records
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/verify-dns-records

api-reference/v01.40.04/openapi-v01.40.04.json post /company/domains/{id}/verify-dns
Verify that all required DNS records (SPF, DKIM, DMARC) are properly configured. Call this after adding all DNS records from the finalize step. Once verified, the domain is ready for sending emails.



# Verify domain ownership
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/verify-domain-ownership

api-reference/v01.40.04/openapi-v01.40.04.json post /company/domains/{id}/verify-ownership
Verify domain ownership by checking the TXT record. Call this after adding the verification TXT record to your DNS. DNS propagation may take up to 48 hours, but typically completes within minutes.



# Verify workspace domain DNS records
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/verify-workspace-domain-dns-records

api-reference/v01.40.04/openapi-v01.40.04.json post /workspace/{workspace_id}/domains/{id}/verify-dns
Verify that all required DNS records (SPF, DKIM, DMARC) are properly configured. Call this after adding all DNS records from the finalize step. Once verified, the domain is ready for sending emails.



# Verify workspace domain ownership
Source: https://docs.firma.dev/api-reference/v01.40.04/email-domains/verify-workspace-domain-ownership

api-reference/v01.40.04/openapi-v01.40.04.json post /workspace/{workspace_id}/domains/{id}/verify-ownership
Verify domain ownership by checking the TXT record. Call this after adding the verification TXT record to your DNS. DNS propagation may take up to 48 hours, but typically completes within minutes.



# Create or update company email template
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/create-or-update-company-email-template

api-reference/v01.40.04/openapi-v01.40.04.json put /company/email-templates/{email_type}
Create or update a company-level email template for a specific type. Company templates are used as defaults for workspaces without workspace-specific templates.



# Create or update workspace email template
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/create-or-update-workspace-email-template

api-reference/v01.40.04/openapi-v01.40.04.json put /workspace/{workspace_id}/email-templates/{email_type}
Create or update a custom email template for a specific type. If a template already exists for this type, it will be updated. A warning is returned if the template body does not contain {{signing_link}}.



# Delete company email template
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/delete-company-email-template

api-reference/v01.40.04/openapi-v01.40.04.json delete /company/email-templates/{email_type}
Delete a company-level email template. Workspaces will fall back to the built-in default template for this type.



# Delete workspace email template
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/delete-workspace-email-template

api-reference/v01.40.04/openapi-v01.40.04.json delete /workspace/{workspace_id}/email-templates/{email_type}
Delete a custom email template. The workspace will revert to using the company-level or default template for this type.



# Get default email templates
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/get-default-email-templates

api-reference/v01.40.04/openapi-v01.40.04.json get /email-templates/defaults/{language}
Retrieve the built-in default email templates for a specific language. These are the templates used when no custom company or workspace templates are configured.



# Get email template placeholders
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/get-email-template-placeholders

api-reference/v01.40.04/openapi-v01.40.04.json get /email-templates/placeholders
Retrieve the list of available placeholders that can be used in email templates. Placeholders are replaced with actual values when emails are sent.



# Get workspace email template
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/get-workspace-email-template

api-reference/v01.40.04/openapi-v01.40.04.json get /workspace/{workspace_id}/email-templates/{email_type}
Retrieve a specific email template by type for a workspace



# List company email templates
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/list-company-email-templates

api-reference/v01.40.04/openapi-v01.40.04.json get /company/email-templates
Retrieve all custom email templates at the company level. Company templates serve as defaults for all workspaces that don't have workspace-specific templates.



# List workspace email templates
Source: https://docs.firma.dev/api-reference/v01.40.04/email-templates/list-workspace-email-templates

api-reference/v01.40.04/openapi-v01.40.04.json get /workspace/{workspace_id}/email-templates
Retrieve all custom email templates for a workspace



# Generate JWT token for embedding templates
Source: https://docs.firma.dev/api-reference/v01.40.04/jwt-management/generate-jwt-token-for-embedding-templates

api-reference/v01.40.04/openapi-v01.40.04.json post /generate-template-token
Creates a JWT token for embedding a template with 24-hour expiration. This is the standard endpoint for JWT generation.

**Note**: The standalone `generate-embedded-template-token` function is deprecated in favor of this router-based endpoint.



# Generate JWT token for signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/jwt-management/generate-jwt-token-for-signing-request

api-reference/v01.40.04/openapi-v01.40.04.json post /jwt/generate-signing-request
Generate a JWT token for embedding a signing request editor. JWT expires after 7 days.



# Revoke a signing request JWT token
Source: https://docs.firma.dev/api-reference/v01.40.04/jwt-management/revoke-a-signing-request-jwt-token

api-reference/v01.40.04/openapi-v01.40.04.json post /jwt/revoke-signing-request
Revoke a previously generated JWT token for a signing request, preventing it from being used for embedded editing



# Revoke Template JWT Token
Source: https://docs.firma.dev/api-reference/v01.40.04/jwt-management/revoke-template-jwt-token

api-reference/v01.40.04/openapi-v01.40.04.json post /revoke-template-token
Revoke a previously generated JWT token, preventing it from being used for template embedding. This is the standard endpoint for revoking template JWTs.



# Create an organization seal
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/create-an-organization-seal

api-reference/v01.40.04/openapi-v01.40.04.json post /seals
Create a new organization seal with an uploaded, typed, or drawn image. Company-scope seals require a protected API key.



# Erase a seal lineage
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/erase-a-seal-lineage

api-reference/v01.40.04/openapi-v01.40.04.json delete /seals/{id}/erase
Permanently erase all versions of a seal lineage. The seal must be revoked first. This is irreversible and removes all image data. Requires a protected API key.



# Get an organization seal
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/get-an-organization-seal

api-reference/v01.40.04/openapi-v01.40.04.json get /seals/{id}
Retrieve a single organization seal by ID.



# Get seal image
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/get-seal-image

api-reference/v01.40.04/openapi-v01.40.04.json get /seals/{id}/image
Retrieve the seal's rendered PNG image as a base64 data URI. Rate limited to 60/min. Each retrieval is audit-logged.



# List organization seals
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/list-organization-seals

api-reference/v01.40.04/openapi-v01.40.04.json get /seals
List organization seal heads for the company. Returns active (non-revoked, non-deleted) seal heads by default. Pass include_revoked=true to include revoked heads.



# List seal access log
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/list-seal-access-log

api-reference/v01.40.04/openapi-v01.40.04.json get /seals/{id}/access-log
Retrieve the access log for a seal's lineage, including creation, replacement, revocation, rename, and image read events.



# List seal applications
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/list-seal-applications

api-reference/v01.40.04/openapi-v01.40.04.json get /seals/{id}/applications
List signing requests where this seal has been applied, is pending, or was paused.



# Revoke an organization seal
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/revoke-an-organization-seal

api-reference/v01.40.04/openapi-v01.40.04.json delete /seals/{id}
Revoke (soft-delete) a seal. Optionally stop pending signing requests that reference it. Company-scope seals require a protected API key.



# Update an organization seal
Source: https://docs.firma.dev/api-reference/v01.40.04/seals/update-an-organization-seal

api-reference/v01.40.04/openapi-v01.40.04.json patch /seals/{id}
Update a seal's name, display name, image, or default status. Any image-class change (image, typed, display_name, signatory_title, statement) creates a new version (replace) and requires a `statement` with accepted true, version 1, language, text equal to the seal's `statement_text` exactly, signatory_name, and optional signatory_title; otherwise the request fails with 400 `SEAL_STATEMENT_REQUIRED`. The new version records this request's acceptance: `signatory_name` and `signatory_title_attested` are the signatory sent, and `attested_at` is the replacement time. Requests already sent keep the version pinned when they were sent; requests sent after the replacement use the new version, and their certificates show the new signatory. The statement text never changes. Company-scope seals require a protected API key for mutations.



# Delete company signer terms
Source: https://docs.firma.dev/api-reference/v01.40.04/signer-terms/delete-company-signer-terms

api-reference/v01.40.04/openapi-v01.40.04.json delete /company/signer-terms/{language}
Delete company-level signer terms for a specific language.



# Delete workspace signer terms
Source: https://docs.firma.dev/api-reference/v01.40.04/signer-terms/delete-workspace-signer-terms

api-reference/v01.40.04/openapi-v01.40.04.json delete /workspace/{workspace_id}/signer-terms/{language}
Delete workspace-level signer terms for a specific language.



# List company signer terms
Source: https://docs.firma.dev/api-reference/v01.40.04/signer-terms/list-company-signer-terms

api-reference/v01.40.04/openapi-v01.40.04.json get /company/signer-terms
Retrieve all company-level signer terms. Company signer terms serve as defaults for workspaces without workspace-specific signer terms.



# List workspace signer terms
Source: https://docs.firma.dev/api-reference/v01.40.04/signer-terms/list-workspace-signer-terms

api-reference/v01.40.04/openapi-v01.40.04.json get /workspace/{workspace_id}/signer-terms
Retrieve all custom signer terms for a workspace



# Create or update company signer terms
Source: https://docs.firma.dev/api-reference/v01.40.04/signer-terms/update-company-signer-terms

api-reference/v01.40.04/openapi-v01.40.04.json put /company/signer-terms/{language}
Create or update company-level signer terms for a specific language. The submitted statement is sanitized before storage.



# Create or update workspace signer terms
Source: https://docs.firma.dev/api-reference/v01.40.04/signer-terms/update-workspace-signer-terms

api-reference/v01.40.04/openapi-v01.40.04.json put /workspace/{workspace_id}/signer-terms/{language}
Create or update workspace-level signer terms for a specific language. The submitted statement is sanitized before storage.



# Get signing request audit trail
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/get-signing-request-audit-trail

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/audit
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.



# Get signing request reminders
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/get-signing-request-reminders

api-reference/v01.40.04/openapi-v01.40.04.json get /signing-requests/{id}/reminders
Retrieve all reminders scheduled for a specific signing request



# Remove a seal participant from an unsent signing request
Source: https://docs.firma.dev/api-reference/v01.40.04/signing-requests/remove-a-seal-participant

api-reference/v01.40.04/openapi-v01.40.04.json delete /signing-requests/{id}/seal-participants/{participant_id}
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.



# Create Webhook
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/create-webhook

api-reference/v01.40.04/openapi-v01.40.04.json post /webhooks
Create a new webhook



# Delete a webhook
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/delete-a-webhook

api-reference/v01.40.04/openapi-v01.40.04.json delete /webhooks/{id}
Soft delete a webhook by ID. This marks the webhook as deleted but retains the data.



# Get Webhook
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/get-webhook

api-reference/v01.40.04/openapi-v01.40.04.json get /webhooks/{id}
Retrieve a specific webhook by ID



# Get webhook secret rotation status
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/get-webhook-secret-rotation-status

api-reference/v01.40.04/openapi-v01.40.04.json get /webhooks/secret-status
Returns information about the current webhook secret including rotation status and expiry of old secret if applicable.



# Get Workspace Webhook Secret Status
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/get-workspace-webhook-secret-status

api-reference/v01.40.04/openapi-v01.40.04.json get /workspaces/{id}/webhooks/secret-status
Returns the status of a workspace webhook secret including creation date, rotation date, and grace period status.



# List Webhooks
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/list-webhooks

api-reference/v01.40.04/openapi-v01.40.04.json get /webhooks
Retrieve a paginated list of webhooks



# Rotate webhook signing secret
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/rotate-webhook-signing-secret

api-reference/v01.40.04/openapi-v01.40.04.json post /webhooks/rotate-secret
Generates a new webhook signing secret for the company. For 7 days after the rotation, Firma also signs deliveries with the previous secret in `X-Firma-Signature-Old`. Only one previous secret is kept: rotating again within the 7 days replaces it. A secret can be rotated once per hour; a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`.



# Rotate Workspace Webhook Secret
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/rotate-workspace-webhook-secret

api-reference/v01.40.04/openapi-v01.40.04.json post /workspaces/{id}/webhooks/rotate-secret
Generates a new webhook signing secret for a workspace. The old secret remains valid for 7 days.



# Test a webhook
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/test-a-webhook

api-reference/v01.40.04/openapi-v01.40.04.json post /webhooks/{id}/test
Send a test payload to the webhook URL to verify it's working correctly



# Update Webhook
Source: https://docs.firma.dev/api-reference/v01.40.04/webhooks/update-webhook

api-reference/v01.40.04/openapi-v01.40.04.json put /webhooks/{id}
Update an existing webhook



# Get workspace settings
Source: https://docs.firma.dev/api-reference/v01.40.04/workspace-settings/get-workspace-settings

api-reference/v01.40.04/openapi-v01.40.04.json get /workspace/{workspace_id}/settings
Retrieve workspace settings



# Update workspace settings
Source: https://docs.firma.dev/api-reference/v01.40.04/workspace-settings/update-workspace-settings

api-reference/v01.40.04/openapi-v01.40.04.json put /workspace/{workspace_id}/settings
Update workspace settings



# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Organization Seals
Source: https://docs.firma.dev/guides/organization-seals

Automate your company's countersignature. Apply your organization's electronic seal to every signed document, with a full audit trail and tamper-evident certificate.

> [!NOTE]
>
> Organization seals are available on all plans at no extra charge. One credit per send covers both recipient signatures and any seal participants on the request.

## What an organization seal is

An organization seal is an electronic seal applied on behalf of a legal entity (your company), not a natural person. It places a company stamp image and metadata on the signed document automatically, without requiring a human to act at signing time.

Use it to automate your company's countersignature: the platform applies the seal at the position you choose in the signing order, so no one on your side has to sign the document by hand.

Each seal carries:

* A **stamp image** (uploaded, typed from the company name, or drawn)
* A **display name** and optional **signatory title**
* An **attestation** recorded at creation, confirming the creator's authority to apply the seal on the company's behalf

The seal appears on the final PDF alongside human signatures. The certificate of completion lists it as a participant with the label "Applied automatically", never "Signed".

## Who can create a seal

Only company owners (the **Owner** role) can create, replace, revoke, or erase organization seals in the dashboard. Company seals live under **Settings > Organization Seals**; workspace seals live under the workspace's **Settings > Organization Seals**.

On the API, a **protected API key** (the key of the company's protected workspace) is required for company-scope seals. Workspace-scope seals accept that workspace's own key or the protected key.

### The authority statement

Every seal requires an attestation before it can be used. The creator reads and accepts a statement confirming they have the authority to bind the company. This acceptance is recorded with:

* The attester's identity (the dashboard user, or the API key that made the call)
* IP address and user agent
* Language and statement version
* A SHA-256 hash of the canonical statement text

### Replacing a seal

Since October 13, 2026, `PATCH /seals/{id}` creates a new version when you send `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Read the seal with `GET /seals/{id}` first. Send `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the returned `statement_text`, and `signatory_name`. Include `statement.signatory_title` if needed. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing.

Each replacement version records its own acceptance: the replacement time (`attested_at`), the user or API key that made it, and the signatory supplied with the replacement (`signatory_name` and `signatory_title_attested`). The statement text, SHA-256 hash, language, statement version, and `authority_name` remain those of seal version 1.

Requests already sent keep the seal version pinned when they were sent. Requests sent after the replacement use the new version; their certificates show the new signatory and attestation date. `POST /seals` creation behavior is unchanged.

For a seal whose `statement_language` is `en`, send this request body to `PATCH /seals/{id}`. Replace the `text` placeholder with the exact `statement_text` from `GET /seals/{id}`. Use the seal's stored language for `language`.

```json theme={null}
{
  "typed": {
    "text": "Acme Corp"
  },
  "statement": {
    "accepted": true,
    "version": 1,
    "language": "en",
    "text": "<exact statement_text from GET /seals/{id}>",
    "signatory_name": "Alex Martin",
    "signatory_title": "Director"
  }
}
```

Seal objects returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `statement_text` and `statement_hash`. The `seal` object in `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks includes them too. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

## Scope and defaults

Seals exist at two levels:

| Level | Who can use it | Default behavior |
| - | - | - |
| **Company** | Any workspace in the company | Falls back to the company default when a workspace has no seals of its own |
| **Workspace** | Only that workspace | Takes precedence: if the workspace has any seal, the workspace default is used |

Set at most one default per scope. The sender can always switch to a different in-scope seal when creating or editing a signing request.

## Adding a seal participant

A seal participant is a slot in the signing order that the system fills automatically. Add seal participants to templates and signing requests alongside human recipients. Recipients and seals share one order space.

### In the editors

In the template editor open the **Template Users** panel in the sidebar; in the signing request editor open the **Signers** panel. Click **Add seal**, pick the seal in the row's dropdown, and drag the row to set its position. The row reads **Applies at send** in the top slot and **Applies after previous** anywhere else.

Select the seal row and place at least one stamp field on the document for it. While a seal row is selected the field palette narrows to stamp, text, and date fields.

### Via the API

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, send a `seal_participants` array. Each entry takes:

```json theme={null}
{
  "seal_participants": [
    {
      "temp_id": "seal-1",
      "seal_id": "<seal-uuid>",
      "order": 1
    }
  ]
}
```

* `temp_id` is a client-chosen id used to assign fields to the seal (`seal_participant_temp_id` on the field)
* `seal_id` is the organization seal to apply; it must be in scope for the request's workspace. On the create routes you can omit it to use the default seal
* `order` is the position in the shared order space. **Order 1** (top slot): the seal applies at send, before any recipient is invited or any credit is charged. **After recipient N**: the seal applies automatically once everyone with a lower order has finished

On `PATCH /signing-requests/{id}` and `PATCH /templates/{id}`, send one `seal_participant` object instead. Without `id` it adds a seal participant (`seal_id`, `order`); with the `id` of an existing one it moves it (`order`) or changes its seal (`seal_id`). On signing requests, `id` with `swap_to_seal_id` swaps a paused one (see Swap below).

`PUT /templates/{id}` takes a `seal_participants` array and replaces the template's whole seal set. It applies each `users` and `deleted_users` entry on its own; entries applied before a failure stay applied, so read the template again after any non-2xx response.

For entries of a `seal_participants` array on the create routes, a seal from another company or scoped to another workspace returns `404 NOT_FOUND`. A revoked, deleted, or replaced (not current) seal returns `409 SEAL_UNAVAILABLE`. If you omit `seal_id` and there is no default seal, the create returns `400 SEAL_UNAVAILABLE`. When organization seals are not enabled, a create with seals returns `503 SEALS_DISABLED`.

When you create, a request without a resolved seal numbers recipients in array order when `use_signing_order` is false or any recipient omits `order`. A document-based create with seals needs an `order` on every recipient and a contiguous order space.

Seal participants own stamp fields (at least one), an optional date field, and text fields populated from `display_name` and `signatory_title`. All seal fields are server-authored and read-only; client-provided values on them are ignored. Give every seal at least one stamp field: sending a signing request whose seal has none returns `400 SEAL_NO_IMAGE_FIELD`.

On `POST /signing-requests` and `POST /signing-requests/create-and-send`, a seal-owned text field can use `seal_attribute` (`display_name` or `signatory_title`) to set which seal property the field prints. Any other non-null value returns `400 VALIDATION_ERROR`; `null` is accepted.

`POST /templates` does not accept `seal_participants`. It ignores the key and returns a `warnings` entry in the `201`. Add seals with `PATCH /templates/{id}` or `PUT /templates/{id}`.

To remove a seal participant and its fields from an unsent request, call `DELETE /signing-requests/{id}/seal-participants/{participant_id}`. The remaining participants are renumbered to close the gap.

#### Creating from a template

When you create with `template_id`, the `seal_participants` key decides what happens to the template's seals:

* Absent or `null`: the request inherits the template's seals and their fields.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is created. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`. An inherited seal limited to another workspace is left out with its fields, and the response lists it with `dropped: true`; every persisted entry has `dropped: false`.

When at least one seal is resolved on a template-based create, the request is renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first on a tie.

Since October 13, 2026, on `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, if the template has no recipients of its own and `seal_participants` is absent or `null`, the inherited seals keep their template order at positions `1..k`; the request's recipients follow at `k+1..`. Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.

`POST /templates/{id}/duplicate` attaches the stored seal version as is (a replaced, revoked, or deleted seal fails when you send) and returns no `seal_participants` for every company during normal operation. While multi-document editing is suspended, duplicating a template on the multi-document read-only path returns `409 MULTI_DOCUMENT_READ_ONLY`. For other templates during that suspension, it copies the template's seals the same way: current version, `409 SEAL_UNAVAILABLE`, `503 SEALS_DISABLED`, and seals limited to another workspace than the target workspace listed with `dropped: true`; it returns `seal_participants`.

#### Reading a template's seals

`GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, or `[]` when the template has none.

#### Changing the order

Signers, approvers, and seals share one order space; CC recipients are separate. On an unsent request, with `PATCH /templates/{id}` or `PATCH /signing-requests/{id}`:

* Move a participant to a position in `[1..n]`. The participants between the old and new positions shift by one. A target above `n` returns `400 INVALID_SIGNING_ORDER`.
* Insert a new participant at a position in `[1..n+1]`. Omit `order` on a new recipient to append it. For a new recipient, `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`. A new seal participant needs a positive integer `order`: a missing or zero value returns `400 VALIDATION_ERROR`, and a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* If participants change concurrently, a write can return `409 PARTICIPANTS_CHANGED`. Reload and retry.

Once a signing request is sent (finished and cancelled requests included), `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`. The one exception: a protected caller can swap a paused seal participant on a request that is not finished or cancelled (see Swap below). `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED` on a sent request, and `409 ALREADY_FINISHED` or `409 ALREADY_CANCELLED` on a finished or cancelled one.

## What the certificate shows

The certificate of completion includes one row per seal participant:

```
Organization seal · Acme Corp · Applied automatically · 2026-09-14 14:32 UTC
```

The Identity column shows one of three values:

| Value | When |
| - | - |
| Company API key | Seal pinned by an API call using a protected key |
| Dashboard | Seal pinned through the dashboard |
| Embedded integration | Seal pinned by an embedded send |

If a seal was paused and then swapped, both events appear on the certificate. No IP address is recorded for seal participants.

## Revoke, stop pending, and swap

### Revoke

Revoking a seal is prospective: new sends cannot use it, but already-pinned participants on sent requests continue to apply their pinned version. Revoke from the seal's menu in the dashboard, or with `DELETE /seals/{id}`.

Choose **stop pending applications** (`DELETE /seals/{id}?stop_pending=true`) to also pause every in-flight participant that has not yet applied. Each paused participant:

* Triggers a `signing_request.seal.paused` webhook
* Emails the sender explaining which request is affected
* Blocks signing progress until the sender resolves it

### Swap

A paused seal participant can be swapped to a different in-scope seal by a company owner from the request view, or via the API with a protected key:

```json theme={null}
PATCH /signing-requests/{id}
{
  "seal_participant": {
    "id": "<participant-id>",
    "swap_to_seal_id": "<seal-uuid>"
  }
}
```

Every swap writes an append-only tracking row. After send, the only exits for a seal participant are **swap** (on a paused participant) or **cancel** the entire request.

## Inspecting a seal

* `GET /seals` lists the seals visible in the key's scope; `GET /seals/{id}` returns one
* `GET /seals/{id}/image` returns the canonical PNG. Every image read is written to the seal's access log
* `GET /seals/{id}/applications` lists the signing requests the seal was applied to
* `GET /seals/{id}/access-log` lists lifecycle and image-read events for the seal

## Erase and retention

Seal versions, attestations, and access-log rows are retained as long as any sent or finished signing request (including test requests) references the version. This is the same standing as signed documents.

A revoked seal lineage that is referenced by **no** request and **no** template may be erased by a company owner 90 days after revocation, in the dashboard or with `DELETE /seals/{id}/erase`. The response lists which templates and requests block erasure if any do. Erasure is logged append-only.

## Webhooks

Organization seals generate seven event types:

### Seal lifecycle events

* `organization_seal.created`: a new seal was created
* `organization_seal.updated`: a seal's image was replaced (new version), it was renamed, or its default flag changed
* `organization_seal.deleted`: a seal was revoked
* `organization_seal.erased`: a revoked seal lineage was permanently erased

### Signing request seal events

* `signing_request.seal.applied`: a seal was applied to a document
* `signing_request.seal.paused`: a seal participant was paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped`: a paused seal participant was swapped to a different seal

Subscribe to these events through the [Webhooks](/guides/webhooks) configuration.

## Prefer a typed name or logo

When creating a seal, prefer a **typed company name** or a **company logo stamp** over a reproduction of a real handwritten autograph. A handwritten image on an organization seal is misleading (it implies a person signed) and may constitute a forgery asset. The typed and drawn modes produce a clean, recognizable mark that honestly represents the company.

## Test mode

Test API keys can create and manage live seals. Test signing requests can apply them. Every test document carries a watermark, so no test artifact is ever unmarked. The PAdES digital seal is applied to test documents where enabled in the workspace.

## Related guides

* [Legal Validity](/guides/legal-validity): where organization seals stand under eIDAS Article 35/36
* [Webhooks](/guides/webhooks): subscribe to seal lifecycle and application events
* [Audit Trail](/guides/audit-trail): the full event schema behind every signing request
* [Sending a Signing Request](/guides/sending-signing-request): add seal participants alongside human recipients


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations


# a0.dev
Source: https://docs.firma.dev/guides/a0dev-integration

Add legally binding e-signatures to any a0.dev mobile app using a backend endpoint and an in-app WebView.

Firma lets you add legally binding e-signatures to any React Native / Expo app generated with a0.dev. Mobile apps need signing constantly: service agreements, parental consent, gig-worker contracts, rental and delivery confirmations. Because a0.dev generates Expo apps, you can present the Firma signing experience in a native WebView while keeping your API key safe on a backend you control.

This guide covers two integration paths:

1. **Backend endpoint + WebView (recommended)** - Send signing requests from a server-side endpoint and present the signing experience in a native WebView. Best for production mobile apps.
2. **Deep link (lightweight)** - Open the Firma signing URL in the system browser. Best for very simple flows.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An a0.dev project (uses Expo + React Native)
* `react-native-webview` installed in the project (add it via a0.dev's AI chat or the import panel)
* At least one Firma template with signing fields configured
* A backend service for your API calls (e.g., Express, Fastify, or a Supabase Edge Function)

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Backend endpoint + WebView**

This is the recommended approach. Your app calls a server-side endpoint to create the signing request, then opens the signing URL in a WebView that lives inside your app. Because a0.dev apps are frontend-only, you need an external backend to keep your API key secure.

### Step 1: Set up a backend endpoint

Create a backend endpoint that calls the Firma API. This can be an Express server, a Supabase Edge Function, or any server-side environment where you can store secrets. Here is an example using Express:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in client-side React Native code. Always call the Firma API from a backend where secrets are kept secure.

### Step 2: Store your backend URL in the app

In your a0.dev project, create a `.env` file and add your backend URL:

```text theme={null}
BACKEND_URL=https://your-backend.example.com
```

Make sure `.env` is in `.gitignore`.

### Step 3: Call the endpoint and open the WebView

From any React Native screen, call the backend endpoint and store the returned `signing_request_user_id`. Then render the Firma signing experience inside a WebView:

```typescript theme={null}
import { useState } from "react";
import { View, Pressable, Text } from "react-native";
import { WebView } from "react-native-webview";

export default function SignContractScreen() {
  const [signingUserId, setSigningUserId] = useState<string | null>(null);

  async function sendForSigning() {
    const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "Consulting Agreement",
        template_id: "your-template-id",
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setSigningUserId(data.signing_request_user_id);
  }

  if (signingUserId) {
    return (
      <WebView
        source={{ uri: `https://app.firma.dev/signing/${signingUserId}` }}
        style={{ flex: 1 }}
        allowsInlineMediaPlayback
        mediaPlaybackRequiresUserAction={false}
      />
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
      <Pressable onPress={sendForSigning}>
        <Text>Send contract for signature</Text>
      </Pressable>
    </View>
  );
}
```

You can also ask the a0.dev AI chat to wire this up: "When the user taps Send Contract on the contract screen, call my backend at /api/signing-requests with the template ID and the user's details, then show the Firma signing WebView."

**Deep link**

If you do not want to host a WebView, open the signing URL in the system browser using `expo-linking`. The signer completes the document in the browser and your app handles the return via webhook.

```typescript theme={null}
import * as Linking from "expo-linking";

async function sendForSigning() {
  const res = await fetch(`${process.env.BACKEND_URL}/api/signing-requests`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Consulting Agreement",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });
  const data = await res.json();
  await Linking.openURL(data.signing_link);
}
```

This is fine for low-stakes flows but loses the in-app experience. The WebView path is preferred for production.

## Webhook integration

To track when documents are signed, add a webhook endpoint to your backend:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

The WebView shown in the getting started section is the mobile equivalent of Firma's embedded signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in a WebView:

```typescript theme={null}
<WebView
  source={{ uri: `https://app.firma.dev/signing/${signingRequestUserId}` }}
  style={{ flex: 1 }}
  allowsInlineMediaPlayback
  mediaPlaybackRequiresUserAction={false}
/>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Anchor Tags
Source: https://docs.firma.dev/guides/anchor-tags

Place fields automatically by matching literal marker text in an uploaded PDF or DOCX, instead of specifying pixel coordinates yourself.

Anchor tags let you position fields on a document by matching text that's already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text - commonly written as `{{SIGN_HERE}}` or similar, though any literal string works - pass an `anchor_tags` array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

> [!NOTE]
>
> Anchor tags only work with document-based creation - a request that includes `document` (base64) or `document_id`. They have no effect on `template_id`-based requests, because the anchor pipeline searches the uploaded document itself; a template's fields are already positioned.

## How matching works

`anchor_string` is matched as literal, case-insensitive-by-default substring text anywhere in the document - there's no required delimiter syntax. `{{...}}` is just a convention that's visually easy to spot in a document and unlikely to collide with real content; `"Sign Here:"` or `"X_____"` work exactly the same way.

Each anchor tag supports:

| Property | Default | Effect |
| :- | :- | :- |
| `case_sensitive` | `false` | Whether the match respects letter case |
| `match_whole_word` | `true` | Requires non-word characters on both sides of the match |
| `occurrence` | `0` | `0` places a field at **every** match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence |
| `ignore_if_not_present` | `false` | If the string isn't found: `true` skips it silently, `false` fails the whole request |
| `x_offset` / `y_offset` | `0` | Shifts the placed field away from the matched text |
| `offset_units` | `percent` | `percent` of page dimensions, or `pixels` (PDF points, 72 DPI) |

> [!WARNING]
>
> If the document has no extractable text at all - a scanned or image-based PDF, for example - no anchor can match. Set `ignore_if_not_present: true` if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

### Default field sizes

If you don't pass `width`/`height` on an anchor tag, the field is sized by `type` (as a percentage of the page):

| Type | Width | Height |
| :- | :- | :- |
| `signature` | 25% | 5% |
| `initial` / `initials` | 10% | 5% |
| `date` | 20% | 3% |
| `text` / `textarea` / `text_area` / `dropdown` / `url` | 20% | 3% |
| `checkbox` / `radio` / `radio_buttons` | 3% | 3% |

> [!WARNING]
>
> `stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` are all accepted as anchor `type` values by the server, but none of the five has a dedicated entry in this table - they silently fall back to the `text` default (20% × 3%). That's usually too small for a stamp, file-upload box, or approval signature. Always pass explicit `width`/`height` when anchoring any of these types.

## Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

| Option | Default | What it actually does |
| :- | :- | :- |
| `remove_anchor_text` | `true` | Sets the anchor string's glyphs to **invisible PDF text rendering mode** in place. The characters stay in the content stream (so surrounding text doesn't reshuffle) but nothing is painted for them. |
| `add_white_background` | `false` | Draws an **opaque white rectangle** over the field's entire bounding box, covering whatever document content sits underneath - not just the anchor string. |

> [!WARNING]
>
> The public API reference currently describes `remove_anchor_text` as "drawing a white rectangle over" the anchor text. That description is stale - it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what `add_white_background` does, and it acts on the whole field box, not the anchor string specifically.
>
> If marker text uses an embedded subset (CID) font or is split across PDF text-show operators, Firma may be unable to hide it. Firma then draws a white box over the matched marker area automatically, even when `add_white_background` is not set. A `no glyph advances for font` error means the marker was inside a PDF Form XObject or transparency group whose glyph positions could not be replayed.

Because `remove_anchor_text` only changes how the text is *painted*, it never removes the string from the document's text layer:

> [!NOTE]
>
> A document processed with `remove_anchor_text: true` (the default) looks like the anchor text is gone in any PDF viewer - but running text extraction (`pdftotext`, a PDF library's `extractText`, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is "still there" after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor's coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options - `remove_anchor_text` hides the marker glyphs, `add_white_background` covers the full field footprint.

## DOCX documents

There's no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

1. The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
2. A DOCX is converted via `mammoth` (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table - it is **not** a rasterization of the original Word pagination.
3. Anchor matching runs against this freshly-rendered PDF.

> [!WARNING]
>
> Because the DOCX→PDF conversion re-lays out content rather than preserving Word's original layout, an anchor's position after conversion depends on where the converter's own renderer places that text - not on where it appeared in the original Word document. Page breaks and line wraps can shift. **Images embedded in the DOCX are dropped entirely during conversion** - the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors - by the time anchor matching runs, the file is already a PDF, so there's no DOCX-specific restriction on which `type` values you can use.

## PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

> [!NOTE]
>
> Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

### PDF vs. DOCX at a glance

| | PDF | DOCX |
| :- | :- | :- |
| Original layout preserved | Yes - matching runs on the exact uploaded file | No - the file is reflowed onto a fixed A4 layout before matching runs |
| Images | Untouched by anchor processing | Dropped during DOCX→PDF conversion |
| Matching pipeline | Runs directly | Runs against the converted PDF (identical logic) |

## Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified `fields` in the same request, and once created they're ordinary field rows - the response doesn't distinguish an anchor-placed field from a manually positioned one, and doesn't expose which anchor string or occurrence produced it.

## Gotchas

### Removed anchor text is hidden, not deleted - plan for it showing up in extraction

As covered above, `remove_anchor_text` never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can't satisfy that - choose anchor strings you're comfortable having permanently present (invisibly) in the file, or don't rely on this API to scrub them.

### Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you've already run through anchor-tag processing still matches the same `anchor_string` values if you pass it (or a copy of it) back into a *new* create request with the same `anchor_tags`. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document - not against a document you already generated from a previous anchor-tag request.

### Anchor-tag font styling mostly doesn't persist

An anchor tag accepts `font_family`, `font_size`, `font_color`, and `text_align`. Only `font_size` actually reaches the created field - it's merged into `format_rules.fontSize` (clamped to 8–48). `font_family`, `font_color`, and `text_align` are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

### `stamp`, `file`, and `approval_*` anchor types need explicit sizing

`stamp`, `file`, `approval_signature`, `approval_checkmark`, and `approval_date` all pass server-side validation as anchor `type` values, but none has a dedicated default-dimensions entry, so all five silently inherit the `text` default (20% × 3%). Pass `width` and `height` explicitly for these types.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Field prefilling](/guides/field-prefilling) - the `read_only`/`read_only_value`/`format_rules.prefilledData` behavior that anchor-placed fields also follow once created
* [Webhooks](/guides/webhooks) - subscribe to webhook events to react as anchor-placed fields are completed


# Antigravity
Source: https://docs.firma.dev/guides/antigravity-integration

Add legally binding e-signatures to any project using Google Antigravity CLI or Antigravity Desktop with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Google Antigravity. Connect Firma's MCP servers to Antigravity CLI or Antigravity Desktop and the agent can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or the IDE.

This guide covers two ways to use Firma with Antigravity:

1. **Antigravity CLI** - Terminal-based agent with MCP support. Best for developers who work in the terminal.
2. **Antigravity Desktop** - Standalone IDE with the same MCP configuration. Best for developers who prefer a visual editor.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Antigravity CLI or Antigravity Desktop installed
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Antigravity CLI**

Antigravity CLI (`agy`) is a terminal-based AI agent that supports MCP servers for external tool integration. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Antigravity CLI

If you haven't already, install the CLI:

```bash theme={null}
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

On Windows (PowerShell):

```powershell theme={null}
irm https://antigravity.google/cli/install.ps1 | iex
```

The binary installs as `agy`. You may need to add `~/.local/bin` to your PATH.

### Step 2: Add the Firma MCP servers

Create or edit `~/.gemini/antigravity/mcp_config.json` and add both Firma servers:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

* **firma-api** gives Antigravity direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Antigravity access to Firma's full documentation so it generates accurate integration code.

Restart the CLI after saving the config. On first use of a Firma tool, Antigravity will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from the CLI

Once connected, you can ask Antigravity to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

**Antigravity Desktop**

Antigravity Desktop is a standalone IDE that uses the same MCP configuration as the CLI. If you have already configured the CLI, the Desktop app picks up the same servers automatically.

### Step 1: Install Antigravity Desktop

Download and install Antigravity Desktop from [antigravity.google](https://antigravity.google).

### Step 2: Add the Firma MCP servers

Antigravity Desktop reads the same config file as the CLI. Create or edit `~/.gemini/antigravity/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "serverUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "serverUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Antigravity Desktop after saving the config.

### Step 3: Build Firma integrations from the IDE

With the MCP servers connected, use the agent chat in Antigravity Desktop the same way you would in the CLI. The agent can read your project files, generate Firma integration code, and wire up endpoints - all within the IDE.

The same prompts from the CLI tab work in the Desktop chat. The Desktop agent has the additional advantage of seeing your full project context, so it can generate code that fits your existing architecture.

## What the agent generates

When you ask Antigravity to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Antigravity to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Migrating from Gemini CLI

If you previously used Firma with Gemini CLI, here is what changed:

| Gemini CLI | Antigravity CLI |
| - | - |
| `~/.gemini/settings.json` | `~/.gemini/antigravity/mcp_config.json` |
| `httpUrl` for remote servers | `serverUrl` for remote servers |
| `gemini` binary | `agy` binary |

Import your existing Gemini CLI plugins:

```bash theme={null}
agy plugin import gemini
```

> [!NOTE]
>
> Gemini CLI stops serving for individual-tier users on June 18, 2026. If you are on a Gemini Code Assist Standard/Enterprise license, the Gemini CLI IDE extensions continue to work.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps the agent write correct integration code. The API server lets the agent manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send. Let the agent pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, ask the agent to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# API Changelog
Source: https://docs.firma.dev/guides/api-changelog

A comprehensive changelog of all API versions and their changes

This document provides a detailed changelog of all Firma API versions, documenting new features, breaking changes, and improvements between each release.

## Version Summary

| Version | Date | Release Type | Key Changes |
| - | - | - | - |
| [v1.40.4](#v1-40-4) | 2026-10-23 | Patch Release | Reference corrections: webhook secret rotation once per hour with one previous secret kept, `409 ALREADY_SENT` and the success example of `POST /signing-requests/{id}/send`, create-and-send failure behavior, `signer_email` partial match and `exclude_deleted` on the list, partial downloads, `document_only_hash`; no API behavior change |
| [v1.40.3](#v1-40-3) | 2026-10-20 | Patch Release | Audit endpoint returns `otp_verified` events (one-time-code evidence) with details; `verify-signing-otp` error responses tightened; no schema change |
| [v1.40.2](#v1-40-2) | 2026-10-19 | Patch Release | Webhook event list corrected: the `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; no API behavior change |
| [v1.40.1](#v1-40-1) | 2026-10-18 | Patch Release | Damaged PDFs: `400 MALFORMED_PDF` with `malformed_pages` when a page of an uploaded PDF has no valid content, on the 11 routes that accept a document; an unreadable PDF returns `400 VALIDATION_ERROR` instead of `500` |
| [v1.40.0](#v1-40-0) | 2026-10-17 | Minor Release | Signing page buttons: `allow_decline` and `show_save_for_later` on company settings, workspace settings, templates, and signing requests hide Decline to Sign and Save & Finish Later (a hidden Decline also refuses declines). `413 REQUEST_TOO_LARGE` for request bodies over 6 MiB |
| [v1.39.1](#v1-39-1) | 2026-10-12 | Patch Release | Organization seals from templates: `POST /signing-requests` and `/create-and-send` with `template_id` inherit the template's seals (an array replaces, `[]` creates without seals), `dropped` entries, `seal_attribute`, `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate` (except for companies enabled for multi-document features), `warnings` on `POST /templates`, order kept relative to template recipients; `seal_participants` filled for every company |
| [v1.39.0](#v1-39-0) | 2026-10-12 | Minor Release | Multiple documents per template and signing request (available to every company): `document_ids` on create, `/documents` routes to add, replace, rename, reorder, remove, and download documents, per-document anchor tags (`document_index`), `documents_layout_version` on field writes, and new error codes. Participant order: one order space for signers, approvers, and seals, shift-insert moves, `INVALID_SIGNING_ORDER`, `SEAL_ORDER_COLLISION`, `SIGNING_ORDER_LOCKED_APPLIED`. Organization seals return `authority_name` |
| [v1.38.0](#v1-38-0) | 2026-09-17 | Minor Release | Catalan (`ca`) support: the platform's supported language set grows to 15, accepted everywhere a language code is accepted, including workspace and company settings, per-signing-request email language, signer terms, email template defaults, and the organization-seal statement language |
| [v1.37.1](#v1-37-1) | 2026-09-15 | Patch Release | CC recipients: accepted on `PUT`/`PATCH` of templates and signing requests, returned in every recipient list, and copied from the template on template-based creation |
| [v1.37.0](#v1-37-0) | 2026-09-14 | Minor Release | Organization seals: seal lifecycle endpoints under `/seals`, `seal_participants[]` on templates and signing requests, seal swap on sent requests, seven new webhook events |
| [v1.36.0](#v1-36-0) | 2026-08-31 | Minor Release | Anchor tags: `add_white_background`; structured error responses (`code`, `errors[]`); `warnings[]` on create-and-send responses |
| [v1.35.0](#v1-35-0) | 2026-08-13 | Minor Release | Cross-workspace template copy: new `POST /templates/{id}/copy` endpoint deep-copies a template to another workspace (protected API key required) |
| [v1.34.0](#v1-34-0) | 2026-08-07 | Minor Release | Completion page customization: custom title, message, redirect URL, and redirect delay at four cascading levels (company, workspace, template, signing request) |
| [v1.33.0](#v1-33-0) | 2026-08-03 | Minor Release | Five new languages — Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), Norwegian Bokmål (`nb`) — accepted everywhere a language code is accepted: workspace/company settings, per-signing-request email language, signer terms, and email template defaults |
| [v1.32.0](#v1-32-0) | 2026-07-22 | Minor Release | Explicit field font size: optional `fontSize` (8-48px) in `format_rules` for text-bearing fields, honored in the signing view and the sealed PDF with auto-shrink preserved; new `font_size` property on anchor tags |
| [v1.31.0](#v1-31-0) | 2026-07-14 | Minor Release | Opt-in per-signing-request email language: new `language` field on create-and-send and update sets the language for all signer-facing emails (falls back to workspace/company default when omitted) |
| [v1.30.0](#v1-30-0) | 2026-07-08 | Minor Release | Signer mark retrieval: signature / initials / stamp images (base64 PNG) and signer-uploaded file download, per signer, via the API |
| [v1.29.0](#v1-29-0) | 2026-07-06 | Minor Release | Two-step document upload (`POST /documents`) for large files up to 50MB; new `document_id` field on create and create-and-send |
| [v1.28.0](#v1-28-0) | 2026-07-05 | Minor Release | TypeScript SDK code samples (`@firma-dev/sdk`) added to every endpoint; embedded signing-request and legacy `/documents` endpoints removed from the reference |
| [v1.27.0](#v1-27-0) | 2026-06-29 | Patch Release | Settings schemas documented: signing-request responses now expose `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, `notify_identity_change_email`; template responses expose `show_qr_code`; `cancel` returns `emails_sent`; `resend` returns `recipients_failed`; new `TemplateSettings` and `LegacyDocumentSettings` schemas |
| [v1.26.0](#v1-26-0) | 2026-06-23 | Minor Release | Workspace settings: signing button label overrides, QR code toggle, presigning download toggle, partial watermark toggle |
| [v1.25.2](#v1-25-2) | 2026-06-18 | Patch Release | Provided fields that match no template field now return `400` (previously ignored silently) on `POST /signing-requests` and `/create-and-send`; field `type` values are matched case-insensitively |
| [v1.25.1](#v1-25-1) | 2026-06-14 | Patch Release | `create-and-send` send-step failures now return the real status (`400`/`402`/`422`) with a machine-readable `code`, instead of masking them as `500` |
| [v1.25.0](#v1-25-0) | 2026-06-14 | Minor Release | Editor brand colors: 5 new appearance fields (`color_accent`, `color_accent_fg`, `color_canvas`, `color_muted`, `color_muted_fg`) on company + workspace settings; resolved `color_palette` now returns 11 keys |
| [v1.24.0](#v1-24-0) | 2026-06-09 | Minor Release | Workspace test API keys: create returns a live+test pair, reads return both, key\_type-aware regenerate/expire |
| [v1.23.0](#v1-23-0) | 2026-06-04 | Minor Release | Signer terms endpoints, company settings endpoints, terms acceptance settings |
| [v1.22.1](#v1-22-1) | 2026-06-02 | Patch Release | Primary/only custom email domain can now be deleted (DELETE no longer returns 400) |
| [v1.22.0](#v1-22-0) | 2026-05-30 | Minor Release | Delete signing request endpoint, signing\_request.deleted webhook event |
| [v1.21.1](#v1-21-1) | 2026-05-19 | Patch Release | Workspace webhook activation via API |
| [v1.21.0](#v1-21-0) | 2026-05-14 | Minor Release | Custom email sender local-part setting |
| [v1.20.0](#v1-20-0) | 2026-05-12 | Minor Release | Guided navigation control setting |
| [v1.19.0](#v1-19-0) | 2026-05-12 | Minor Release | Logo management endpoints, workspace icon\_url |
| [v1.18.0](#v1-18-0) | 2026-05-06 | Minor Release | Identity editable fields, editable prefilled data, field value validation |
| [v1.17.0](#v1-17-0) | 2026-05-01 | Minor Release | Color customization for signing experience |
| [v1.16.0](#v1-16-0) | 2026-04-27 | Minor Release | Download Signing Request endpoint |
| v1.15.3 | 2026-04-27 | Minor | Clean field aliases |
| [v01.15.02](#v01-15-02) | 2026-04-23 | Patch Release | Added missing field types to create-and-send fields schema |
| [v01.15.01](#v01-15-01) | 2026-04-17 | Patch Release | Added Russian and Polish language support to API schemas |
| [v01.15.00](#v01-15-00) | 2026-04-16 | Minor Release | Workspace Webhooks, Secret Rotation/Status Endpoints |
| [v01.14.00](#v01-14-00) | 2026-04-14 | Minor Release | Approver/CC Designations, Approval Field Types |
| [v01.13.00](#v01-13-00) | 2026-04-12 | Minor Release | Stamp Field Type |
| [v01.12.01](#v01-12-01) | 2026-04-02 | Patch Release | Custom Field Variable Names (`variable_defined_name`) |
| [v01.12.00](#v01-12-00) | 2026-03-26 | Minor Release | MCP Server Integration |
| [v01.11.00](#v01-11-00) | 2026-03-19 | Minor Release | File Upload Fields, Anchor Tags, Field Background Colors, Signing Order Default Change |
| [v01.10.00](#v01-10-00) | 2026-03-10 | Minor Release | Conditional Fields, DOCX Support, Audit Trail, Signature Frame Control |
| [v01.09.00](#v01-09-00) | 2026-03-05 | Minor Release | OTP Verification, Replace Template Document |
| [v01.08.00](#v01-08-00) | 2026-03-03 | Minor Release | Email Templates API, Language Support, Webhook Observability |
| [v01.07.00](#v01-07-00) | 2026-02-25 | Minor Release | Hand-Drawn Signatures, Legacy Settings Fields |
| [v01.06.00](#v01-06-00) | — | Minor Release | Split PDF Downloads, Field Type Normalization |
| [v01.05.00](#v01-05-00) | — | Patch Release | Email Validation Warnings |
| [v01.04.00](#v01-04-00) | — | Minor Release | New Field Types, PATCH Field Operations, Template User Matching |
| [v01.03.00](#v01-03-00) | — | Minor Release | Email Domains API, Credit Cost, Declined Status |
| [v01.02.00](#v01-02-00) | — | Minor Release | Enhanced User Fields, Ready-to-Send Indicators |
| [v01.01.00](#v01-01-00) | — | Minor Release | Template CRUD, API Key Management, Comprehensive Updates |
| [v01.00.02](#v01-00-02) | — | Patch Release | Custom Fields API |
| [v01.00.01](#v01-00-01) | — | Initial Release | Core API Features |

***

## v1.40.4

**Release Date:** October 23, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.4 spec](/api-reference/v01.40.04/openapi-v01.40.04.json)

### Reference corrections

The OpenAPI spec now describes what the API already does in these places. The API itself has not changed.

* **Webhook secret rotation.** `POST /webhooks/rotate-secret` and `POST /workspaces/{id}/webhooks/rotate-secret` allow one rotation per hour (the spec said one per minute); a second call within the hour returns `429` with code `COOLDOWN_ACTIVE`. Only one previous secret is kept: rotating again within the 7-day overlap replaces it. The `X-RateLimit-Limit` header of `POST /webhooks/rotate-secret` now says 60 requests per minute.
* **Sending a request.** `POST /signing-requests/{id}/send` on a request that was already sent returns `409` with code `ALREADY_SENT` (the spec said `400`), and `409` with code `SEND_IN_PROGRESS` while another send is running. A cancelled or declined request returns `400`. The success example now matches the response: `success`, `message`, `sentTo`, `sentAt`. Its `X-RateLimit-Limit` header now says 120 requests per minute.
* **Create and send.** When the send step of `POST /signing-requests/create-and-send` fails before any part of the send has started, the signing request is removed and an error is returned; no draft is left behind. If the send had already started, the request is kept and the `409` response carries its `signing_request_id`.
* **Listing signing requests.** On `GET /signing-requests`, `signer_email` is a case-insensitive partial match (the spec said exact). Soft-deleted requests are included by default with status `deleted`; the `exclude_deleted=true` parameter, now documented, leaves them out.
* **Partial downloads.** `GET /signing-requests/{id}/download` returns a partial-progress snapshot for any sent request that is not finished. There is no `allow_partial_download` setting. A finished request whose completion certificate is still being generated returns `409`.
* **`document_only_hash`.** The description now says which file it hashes: the sealed per-document PDF, not the uploaded file and not the final PDF with the certificate.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If your retry logic for `POST /signing-requests/{id}/send` expected `400` for an already-sent request, handle `409 ALREADY_SENT` instead.

***

## v1.40.3

**Release Date:** October 20, 2026

**Release Type:** Patch Release

### One-time-code evidence in the audit trail

The audit trail now records that a signer entered the one-time code, with a reference to the verified code record, and `verify-signing-otp` answers more precisely when a code cannot be verified.

* **Audit events.** `GET /signing-requests/{id}/audit` returns `otp_verified` events with `details.channel = "email"` and `details.otp_code_id`, described as `Entered the one-time code sent by email`. `document_finished` events carry `details.otp_code_id` when the finishing session was linked to a verified code. This applies to requests under 1,000 tracking rows; larger requests keep today's truncation.
* **`verify-signing-otp` responses.**
  * A database fault returns `500 INTERNAL` instead of `OTP_NOT_FOUND`.
  * An unknown signer returns `404 SIGNING_USER_NOT_FOUND`.
  * A signer of a deleted request returns `404 SIGNING_REQUEST_NOT_FOUND`. Before, a live code on a deleted request still verified.
  * A malformed `signingUserId` returns `400 INVALID_INPUT`.
  * A request that can no longer be verified (cancelled, declined, expired, already signed, not yet sent, not the signer's turn, or seal paused) returns `200` with `code: "SIGNING_STATE_CHANGED"` and `state`.
  * A correct code with a transient fault no longer consumes an attempt.
* **No OpenAPI schema change.** `event` remains free text. This release adds no reference version and links no OpenAPI document.
* **Admin audit descriptions.** `GET /signing-requests/{id}/audit` and the dashboard audit trail describe a cancel from the dashboard as `Signing Request Cancellation requested` and a delete from the dashboard as `Signing Request Deletion requested`. A certificate retry adds `Certificate regeneration requested`. Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race; "requested" does not confirm completion. Rows written before this release keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

***

## v1.40.2

**Release Date:** October 19, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.2 spec](/api-reference/v01.40.02/openapi-v01.40.02.json)

### Webhook event list

The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` in the OpenAPI spec now names the 26 events Firma.dev sends, the same events the [Webhooks guide](/guides/webhooks) describes. Since v1.37.0 the list had named events the API refuses and left out events it sends. The API itself has not changed.

* Added, already sent: `signing_request.updated`, `signing_request.certificate.generated`, `signing_request.reminder.sent`, `signing_request.recipient.signed`, `signing_request.recipient.declined`, and `signing_request.recipient.identity_changed`.
* Removed, never accepted by the API (a request that names one returns `400 VALIDATION_ERROR`): `signing_request.declined`, `signing_request.voided`, `signing_request.field.completed`, `signing_request.resent`, and `signing_request.credits.purchased`. For a signer who declines, subscribe to `signing_request.recipient.declined`; for a cancelled request, to `signing_request.cancelled`.
* Removed, accepted by the API but never sent: `template.created`, `template.deleted`, `template.field.added`, and `workspace.deleted`. A webhook that names them stays valid, but no event of these types arrives.

### Migration notes

* No change to requests, responses, or webhook deliveries.
* If you generated a client or validation from the spec, regenerate it: the old list refused events you can subscribe to and offered events the API refuses.

***

## v1.40.1

**Release Date:** October 18, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.40.1 spec](/api-reference/v01.40.01/openapi-v01.40.01.json)

### Damaged PDFs

Since October 18, 2026, Firma.dev refuses a PDF in which a page has no valid content, for example a page whose content points to another page's data instead of its own drawing instructions. Such a page renders blank, and Firma.dev cannot generate the completion certificate of a request that contains it. The request returns `400 MALFORMED_PDF`:

```json theme={null}
{
  "error": "The PDF is damaged: page 12 has no valid content. Repair or re-export the file, then upload it again.",
  "code": "MALFORMED_PDF",
  "malformed_pages": [12],
  "document_position": 1
}
```

* `malformed_pages` lists the 1-based numbers of the damaged pages. The message names the first.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, `document_position` (1-based, in the request's document order) names the document, and `document_id` is added when the document came from `document_id` or `document_ids`.
* Nothing is written: no template, no signing request, no credit charge, no email.
* On `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /templates`, an upload named by `document_id` or `document_ids` is used up when this error is returned: upload the repaired file with `POST /documents` again for a new id. On the `/documents` add and replace routes, the upload is kept.
* Re-exporting the file from the application that created it, or saving it again from a PDF editor, usually repairs it.

The routes that return it are the ones that accept a document: `POST /templates`, `PATCH /templates/{id}`, `PUT /templates/{id}`, `POST /templates/{id}/replace-document`, `POST /templates/{id}/documents`, `PATCH /templates/{id}/documents/{document_id}`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /signing-requests/{id}/documents`, and `PATCH /signing-requests/{id}/documents/{document_id}`.

### Unreadable PDFs

Since October 17, 2026, a document that cannot be read as a PDF, including an encrypted PDF, returns `400 VALIDATION_ERROR` with the message `The uploaded document is not a readable PDF` on the same routes. Before, it returned `500`. The `/documents` add and replace routes already answered this way, and now also do for a file that starts like a PDF but whose page tree cannot be read.

### Migration notes

* Requests with valid PDFs behave as before.
* Where you upload documents, handle `400 MALFORMED_PDF`: show the message and ask for a repaired file. Sending the same file again returns the same error.
* If you parse error responses strictly, accept `malformed_pages`, `document_position`, and `document_id`.
* An unreadable PDF now returns `400`, not `500`. Do not retry it.

***

## v1.40.0

**Release Date:** October 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.40.0 spec](/api-reference/v01.40.00/openapi-v01.40.00.json)

### Signing page buttons

Two new settings control the buttons that signers and approvers see on the signing page, hosted or embedded:

* `allow_decline` shows the **Decline to Sign** button. When it is `false`, the button is hidden for every signer and approver, and Firma.dev also refuses a decline. No one can decline the signing request in Firma.dev, so it can only be stopped by cancelling it.
* `show_save_for_later` shows the **Save & Finish Later** button. When it is `false`, only the button is hidden.

Firma.dev uses the signing request's value. When it is `null`, the workspace's value applies, and when that is `null` too, the company's. The company default is `true`, so signing pages are unchanged until you set a value.

| Level | Set with | Values |
| - | - | - |
| Company | `PUT /company/settings` | `true` or `false`. Default `true` |
| Workspace | `PUT /workspace/{workspace_id}/settings` | `true`, `false`, or `null` to use the company value |
| Template | `settings` on `POST /templates` and `PATCH /templates/{id}`; `template_properties.settings` on `PUT /templates/{id}` | `true`, `false`, or `null` |
| Signing request | `settings` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH /signing-requests/{id}`; `signing_request_properties.settings` on `PUT /signing-requests/{id}` | `true`, `false`, or `null` to use the workspace value |

* A signing request created from a template (`template_id` on `POST /signing-requests` and `POST /signing-requests/create-and-send`, or `POST /templates/{id}/duplicate`) copies the template's values when it is created. On the two create routes, a value in the request's `settings` replaces the template's; `null` there means the workspace value. `POST /templates/{id}/duplicate` always copies the template's values. Changing the template later does not change signing requests already created from it.
* `POST /templates/{id}/copy` copies both values to the new template.
* A change to the workspace or company value applies to every signing request whose own value is `null`, including requests already sent and requests created before this release.
* Responses return the values as `true`, `false`, or `null`: in `settings` on templates (`GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`) and signing requests (`GET /signing-requests`, `GET /signing-requests/{id}`, and the create responses), and at the top level of `GET /company/settings` and `GET /workspace/{workspace_id}/settings`. The company values are always `true` or `false`.
* Any other value, such as a string or a number, returns `400 VALIDATION_ERROR` naming the key (for example `settings.allow_decline must be a boolean or null`) and writes nothing. `PUT /company/settings` also refuses `null`.

### Request size limit

Since October 13, 2026, a request body larger than 6,291,456 bytes (6 MiB) returns `413 REQUEST_TOO_LARGE` with the standard `error` and `code` body. Before, the gateway answered `502`. The API reference documents it on `POST /templates`, `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `POST /documents`.

To send a larger document, request an upload URL with `POST /documents`, upload the file to it, and pass `document_id` or `document_ids` instead of inline base64.

### Migration notes

* The change is additive. Requests that never send `allow_decline` or `show_save_for_later` behave as before, and both buttons stay visible until a value is set.
* If you parse responses strictly, accept the two new keys in template, signing request, workspace settings, and company settings responses.
* If you send large inline base64 documents, handle `413 REQUEST_TOO_LARGE`, or upload through `POST /documents`.

***

## v1.39.1

**Release Date:** October 12, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.39.1 spec](/api-reference/v01.39.01/openapi-v01.39.01.json)

### Update, October 13, 2026

* On `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id`, when the template has no recipients of its own and `seal_participants` is absent or `null`, inherited seals now keep their template order first (`1..k`), followed by the request's recipients (`k+1..`). Explicit replacement arrays, templates with recipients, and requests without seals retain their existing order behavior.
* Replacements through `PATCH /seals/{id}` now require `statement` with `accepted: true`, `version: 1`, `language`, `text` exactly equal to the stored `statement_text` from `GET /seals/{id}`, and `signatory_name` (`signatory_title` optional). This applies to changes in `image`, `typed`, `display_name`, `signatory_title`, or `statement`. Without `statement`, the request returns `400 SEAL_STATEMENT_REQUIRED` and writes nothing. `POST /seals` creation behavior is unchanged.
* Each replacement records its own attestation time, caller, and supplied signatory. Statement text, hash, language, statement version, and `authority_name` remain those of seal version 1. Requests already sent keep their pinned version; requests sent after replacement use the new version, whose signatory and attestation date appear on their certificates.
* Seal objects in `POST /seals`, `GET /seals`, `GET /seals/{id}`, `PATCH /seals/{id}`, and the `organization_seal.created`, `organization_seal.updated`, and `organization_seal.deleted` webhooks now include `statement_text` and `statement_hash`. Attester user and API key IDs, IP address, and user agent are excluded from these seal objects.

### Organization seals from templates

`POST /signing-requests` and `POST /signing-requests/create-and-send` with a `template_id` now copy the template's seal participants and their seal fields. The `seal_participants` key decides what happens:

* Absent or `null`: the request inherits the template's seals.
* An array: the array replaces the template's seals. The template's seal fields are not copied.
* `[]`: the request is created without seals.
* Any other type returns `400 VALIDATION_ERROR`. This is checked on every create route, with or without `template_id`.

Body fields only override template fields, so on a template that has fields a replacement array's seals cannot get a stamp field in that call, and sending returns `400 SEAL_NO_IMAGE_FIELD`. To use your own seals with their fields, create from a document, or, on `POST /signing-requests` only, use a template without fields and assign body fields with `seal_participant_temp_id`. Otherwise inherit the template's seals.

An inherited seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the create returns `409 SEAL_UNAVAILABLE` and nothing is written. If at least one inherited seal is kept and organization seals are not enabled, the create returns `503 SEALS_DISABLED`.

An inherited seal that is limited to another workspace than the request's, or that the API key's company cannot see, is left out, along with its fields. It is listed in the response with `dropped: true`, after the other entries. Every other entry carries `dropped: false`.

```json theme={null}
{
  "id": null,
  "order": null,
  "seal": { "id": "<seal-uuid>", "lineage_id": "<lineage-uuid>", "name": "Acme Corp", "version": 2, "display_name": "Acme Corp" },
  "seal_out_of_scope": true,
  "dropped": true
}
```

`seal` is `null` when the API key's company cannot see the seal. A company-wide seal is never left out.

#### Order with a template

When a create with `template_id` resolves at least one seal, recipients and seals are renumbered `1..n`. Inherited seals keep their positions relative to the template's recipients. Seals in a replacement array are placed by their `order`. A seal comes first when it ties with a recipient. Such a create returns `201` where it used to return `400 INVALID_SIGNING_ORDER` or `400 SEAL_ORDER_COLLISION`. The response reports the renumbered orders.

* Since October 13, 2026, if the template has no recipients and `seal_participants` is absent or `null`, inherited seals keep their template order first (`1..k`); the request's recipients follow (`k+1..`).
* On `POST /signing-requests`, a numeric `recipient_id` on a field keeps counting recipients as they would be numbered without the seal.
* Document-based creates (`document`, `document_id`, `document_ids`) with explicit seal participants are unchanged: the raw order checks apply.

#### Seal fields and sending

A seal needs at least one stamp field. Create does not check this, but sending a signing request whose seal has no stamp field returns `400 SEAL_NO_IMAGE_FIELD`. Give every seal at least one stamp field.

### Duplicating a template

Except for companies enabled for multi-document features, `POST /templates/{id}/duplicate` copies the template's seal participants and their fields into the new signing request, and returns them in `seal_participants` (`[]` when there are none). Each kept seal uses the current version of its seal. If the seal has no current version, or that version is revoked or deleted, the route returns `409 SEAL_UNAVAILABLE`. A seal limited to another workspace than the target workspace, or that the API key's company cannot see, is left out and listed with `dropped: true`. If at least one seal is kept and organization seals are not enabled, the route returns `503 SEALS_DISABLED`. Both errors are returned before anything is written.

For companies enabled for multi-document features, this route attaches the template's stored seal version as is. A seal that was replaced, revoked, or deleted since then fails when you send. The response has no `seal_participants` key.

### seal\_attribute

A seal-owned text field takes `seal_attribute`: `display_name` or `signatory_title`. It sets which seal property the field prints. `POST /signing-requests` and `POST /signing-requests/create-and-send` accept it, from a document or a template. Any other value returns `400 VALIDATION_ERROR`; `null` is accepted.

* `POST /signing-requests/create-and-send` from a document now keeps `seal_attribute`. Before, it was dropped.
* A seal field copied from a template keeps the template field's formatting. `seal_attribute` on the request replaces only which property it prints.

### Templates

* `GET /templates/{id}` and `PUT /templates/{id}` return `seal_participants`, ordered by `order`, `[]` when the template has none. Each entry has the shape of seal participants elsewhere.
* `POST /templates` does not accept `seal_participants`, `recipients`, or `fields`. It ignores them and returns a `warnings` array with one string per key present, for example `seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}`. Without those keys the response is unchanged.

### Other changes

* Fixed: `seal_participants` on `GET /signing-requests/{id}`, `GET /signing-requests`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` now returns each organization seal participant with its seal (id, lineage, version, name and display name) for every company. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. This fix changes only what the API returns; stored documents, signatures, and webhooks are not changed by it.
* Completion certificates now draw the applied seal's stamp, date, and text fields, and list each seal participant in the signers table, in signing order. The certificate is not generated while a seal is still outstanding (not applied, or paused). A seal applied automatically at completion, without a triggering recipient, no longer blocks the certificate; its audit line reads "after all preceding participants completed" (in the certificate's language).

### Documentation and API reference

The API reference for this version documents the following. They describe answers the API already gave.

* Each entry of `seal_participants` on `POST /signing-requests` and `POST /signing-requests/create-and-send` requires `temp_id` and `order`. `seal_id` is optional: without it the workspace's default seal is used or, when the workspace has none, the company's default seal, and the call returns `400 SEAL_UNAVAILABLE` when neither exists. The reference had `seal_id` as required and `temp_id` as optional.
* The `seal_participant` body of `PATCH /signing-requests/{id}` and `PATCH /templates/{id}` is documented as the API reads it: `id`, `seal_id`, `order`, and on signing requests `swap_to_seal_id`. The key `participant_id` that earlier references showed was never read; use `id`. Adding a seal participant answers `201` and updating or swapping one answers `200`, both with `{ "seal_participant": ... }`. These routes return `503 SEALS_DISABLED` when organization seals are not enabled and a seal participant is added or its seal is changed. On `PATCH /signing-requests/{id}`, a field that belongs to a seal participant accepts only position and page changes; other keys, `recipient_id` included, are ignored.
* A seal swap on `PATCH /signing-requests/{id}` documents its answers: `403 PROTECTED_KEY_REQUIRED` when the API key is not of the protected workspace; `404 NOT_FOUND` when the new seal does not exist, belongs to another company, or is limited to another workspace; `409 SEAL_UNAVAILABLE` when the new seal is revoked, deleted, or not the current version; `409 SEAL_MUTATION_NOT_ALLOWED` when the request was not sent or the participant is not paused; `400 SEAL_FIELD_REQUIRED` when the participant has no stamp field.
* The `200` body of `DELETE /signing-requests/{id}/seal-participants/{participant_id}` is `{ "deleted": true }`.
* The `fields` array of the `POST /signing-requests/create-and-send` response lists all active fields, including the fields owned by seal participants. Each item is the stored field record, not the `Field` shape used in requests (for example the type is in `field_type`).
* `POST /templates/{id}/copy` documents its `seal_participants` (unchanged behaviour).
* `PUT /templates/{id}` documents its `seal_participants` request array (`TemplateSealParticipantInput`), which replaces the template's seal set.
* The `400` of `POST /signing-requests/create-and-send` lists `SEAL_NO_IMAGE_FIELD` (a seal without a stamp field refused when sending).
* Settings whose `null` has a meaning (`require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, `terms_url`, a field's `recipient_id` or `assigned_to_user_id`, `identity_editable_fields`, and the workspace settings `show_signature_frame` and `show_partial_watermark`) now state what `null` does.

### Migration notes

* For seal replacements from October 13, 2026 onward, read `GET /seals/{id}` and send `statement` on `PATCH /seals/{id}`: `accepted: true`, `version: 1`, `language`, the exact stored `statement_text` as `text`, and `signatory_name` (`signatory_title` optional). Handle `400 SEAL_STATEMENT_REQUIRED` and accept `statement_text` and `statement_hash` in seal objects.
* A `POST /signing-requests` or `POST /signing-requests/create-and-send` with `template_id` and no `seal_participants` key now inherits the template's seals. Send `"seal_participants": []` to create without them. `null` inherits too (including a client that sends `null` for an unset field).
* A `seal_participants` value that is not an array or `null` now returns `400 VALIDATION_ERROR` on `POST /signing-requests` and `POST /signing-requests/create-and-send`; before, it was ignored.
* If you parse responses strictly, accept the new keys: `dropped` on create responses, `warnings` on `POST /templates`, and `seal_participants` on `GET /templates/{id}`, `PUT /templates/{id}`, and `POST /templates/{id}/duplicate`.

***

## v1.39.0

> [!NOTE]
>
> **Update, October 13, 2026:** Multi-document features are available to every company. No enablement is needed. The enablement restrictions in the original release notes below describe the initial rollout.

**Release Date:** October 12, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.39.0 spec](/api-reference/v01.39.00/openapi-v01.39.00.json)

### Multiple documents per template and signing request

A template or signing request can now hold up to 20 documents, with a limit of 100 MB per document set. You can create one from several uploads, then add, replace, rename, reorder, remove, and download its documents one at a time.

> [!NOTE]
>
> At launch, before October 13, 2026, multi-document features required enablement for your workspace's company. This covered the `/documents` routes, `document_ids` with more than one id, per-document anchor tags (`anchor_tags[].document_index`), and the `documents`, `documents_version`, and `documents_layout_version` response keys. At that time, if a company was not enabled:
>
> * The `/documents` routes return `404 NOT_FOUND`, exactly like an unknown endpoint.
> * The three response keys are absent.
> * `document_index` on an anchor tag is not applied: a single-document create accepts it with an unknown-property warning and uses the only document.
> * `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` with more than one entry in `document_ids` (repeated ids count) return `409 MULTI_DOCUMENT_READ_ONLY` before anything is created.

While multi-document editing is suspended, writes to a multi-document template or signing request return `409 MULTI_DOCUMENT_READ_ONLY`. Reads keep working.

#### Creating with several documents

`POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send` accept `document_ids`. Pass 1 to 20 temporary upload ids from `POST /documents`, in document order.

* Send exactly one document source: `document`, `document_id`, or `document_ids` (or `template_id` on the signing-request routes). Sending more than one returns `400 CONFLICTING_DOCUMENT_SOURCE`.
* A repeated id returns `400 DUPLICATE_DOCUMENT_ID`. More than 20 ids return `400 MAX_DOCUMENTS_EXCEEDED`. An unknown or expired upload returns `400 DOCUMENT_UPLOAD_NOT_FOUND`. A set above 100 MB returns `413 DOCUMENT_SET_TOO_LARGE`.
* `document` is no longer marked as required on `POST /templates`, because `document_id` or `document_ids` can take its place.

#### Per-document anchor tags

For enabled companies, anchor tags take a new `document_index`: the 1-based position in `document_ids` of the document to search. It is only meaningful for multi-document requests.

* With one document, `document_index` is optional and defaults to `1`.
* With more than one document, it is required. A missing value returns `400 ANCHOR_DOCUMENT_REQUIRED`; a value out of range returns `400 VALIDATION_ERROR`.

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/templates/{id}/documents` | Add a document (a temporary upload from `POST /documents`) at `position`, or last |
| `PATCH` | `/templates/{id}/documents/{document_id}` | Replace the document with a new upload (`document_id`) or rename it (`label`); send exactly one |
| `PUT` | `/templates/{id}/documents/order` | Reorder: `document_ids` must list every document of the template exactly once |
| `DELETE` | `/templates/{id}/documents/{document_id}` | Remove a document; the last remaining document cannot be removed |
| `POST` | `/signing-requests/{id}/documents` | Add a document at `position`, or last |
| `PATCH` | `/signing-requests/{id}/documents/{document_id}` | Replace or rename a document |
| `PUT` | `/signing-requests/{id}/documents/order` | Reorder the signing request's documents |
| `DELETE` | `/signing-requests/{id}/documents/{document_id}` | Remove a document |
| `GET` | `/signing-requests/{id}/documents/{document_id}/download` | Signed URL (valid for 1 hour) to one document: `type=original` (default) for the document as uploaded, `type=document` for the individually sealed document once the certificate is bound |

Every add, replace, rename, reorder, and remove returns the full document set after the change, with `documents`, `documents_version`, and `documents_layout_version`.

* A replacement must have the same number of pages, and every page must be the same size within 1 pt. Otherwise it returns `400 PAGE_COUNT_MISMATCH` or `400 DIMENSION_MISMATCH`. On a signing request, a document placed with anchor tags is replaced only when the replacement's anchors resolve exactly as stored. Otherwise it returns `400 ANCHOR_MISMATCH`.
* A sent, finished, cancelled, or declined signing request returns `409 DOCUMENT_SET_LOCKED` on every document write.
* A document id that is not part of the template or signing request returns `404 DOCUMENT_NOT_FOUND`. A missing or repeated id in a reorder returns `400 INVALID_DOCUMENT_ORDER`. Removing the last document returns `400 MIN_DOCUMENTS_REQUIRED`.
* The download returns `404 DOCUMENT_ORIGINAL_NOT_AVAILABLE` when the uploaded file is no longer stored, and `404 DOCUMENT_SIGNED_NOT_AVAILABLE` before the certificate is bound.

#### Documents in responses

For enabled companies, these responses carry `documents`, `documents_version`, and `documents_layout_version`: `GET /templates`, `GET /templates/{id}`, `POST /templates`, `PUT /templates/{id}`, `GET /signing-requests`, and `GET /signing-requests/{id}`.

* Each entry of `documents` has `document_id`, `position`, `label`, `original_filename`, `page_count`, and `document_url_kind`. Outside list responses, each entry also includes a signed `document_url`, valid for 1 hour. Signing requests also include `document_only_hash`, the SHA-256 of the individually sealed document once the certificate is bound.
* A template or signing request whose document set has never been changed returns its one document with `document_id: null`. In list responses, it shows `documents: []`.
* `documents_version` increases with every document change. `documents_layout_version` increases when documents are added, removed, or reordered.

#### Field writes on multi-document templates and signing requests

`PUT` and `PATCH` on `/templates/{id}` and `/signing-requests/{id}` accept `documents_layout_version` alongside field writes. Send the value from your last read.

* It is required for a field write when there is more than one document or the layout version is above 1. A missing value returns `409 DOCUMENTS_LAYOUT_VERSION_REQUIRED`.
* A stale value returns `409 DOCUMENT_SET_VERSION_CONFLICT`. Reload and retry.
* A value that is not a non-negative integer returns `400 VALIDATION_ERROR` with the key `documents_layout_version`. A field placed on a page beyond its document's page count returns `400 VALIDATION_ERROR` with the key `page`.
* An inline `document` on `PATCH /signing-requests/{id}` for a request with more than one document returns `409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED`. Use the `/documents` routes instead.

#### Templates with several documents

* `POST /templates/{id}/copy` copies a template with more than one document as a template with one merged document. The content and the absolute page numbers of its fields are kept. The per-document labels and positions are not carried over.

#### Create and send conflicts

`POST /signing-requests/create-and-send` can return `409` with `MULTI_DOCUMENT_READ_ONLY`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, or `DOCUMENT_SET_DISPATCH_STALE`.

`SEND_EFFECTS_EXIST` and `ALREADY_SENT` can also carry `signing_request_id`. It is present when the signing request this call created was kept. Recover that request instead of retrying, because a retry creates a second request. Without `signing_request_id`, no request was kept.

#### Error codes

New codes, all returned as `{ error, code }`:

| Code | Status | Meaning |
| - | - | - |
| `MULTI_DOCUMENT_READ_ONLY` | 409 | Multi-document editing is suspended, or a create with more than one entry in `document_ids` for a company that is not enabled |
| `CONFLICTING_DOCUMENT_SOURCE` | 400 | More than one of `document`, `document_id`, `document_ids`, `template_id` |
| `DUPLICATE_DOCUMENT_ID` | 400 | The same upload id appears twice in `document_ids` |
| `MAX_DOCUMENTS_EXCEEDED` | 400 | More than 20 documents |
| `MIN_DOCUMENTS_REQUIRED` | 400 | The last remaining document cannot be removed |
| `DOCUMENT_UPLOAD_NOT_FOUND` | 400 | Unknown or expired temporary upload |
| `DOCUMENT_SET_TOO_LARGE` | 413 | The document set would exceed 100 MB |
| `ANCHOR_DOCUMENT_REQUIRED` | 400 | An anchor tag without `document_index` on a multi-document create |
| `PAGE_COUNT_MISMATCH` | 400 | The replacement document has a different number of pages |
| `DIMENSION_MISMATCH` | 400 | The replacement document has different page dimensions |
| `ANCHOR_MISMATCH` | 400 | The replacement's anchors do not resolve as stored |
| `INVALID_DOCUMENT_ORDER` | 400 | A reorder that misses or repeats a document |
| `DOCUMENT_NOT_FOUND` | 404 | No document with this id on the template or signing request |
| `DOCUMENT_ORIGINAL_NOT_AVAILABLE` | 404 | The uploaded file is no longer stored |
| `DOCUMENT_SIGNED_NOT_AVAILABLE` | 404 | The individually sealed document is not available yet |
| `DOCUMENT_SET_LOCKED` | 409 | The signing request was sent, finished, cancelled, or declined |
| `DOCUMENTS_LAYOUT_VERSION_REQUIRED` | 409 | A field write without `documents_layout_version` |
| `DOCUMENT_SET_VERSION_CONFLICT` | 409 | The documents changed since your last read; reload and retry |
| `DOCUMENT_SET_BUSY` | 409 | Another action is changing the documents; retry in a moment |
| `DOCUMENT_SET_DISPATCH_STALE` | 409 | The document settings changed during the request; reload and retry |
| `DOCUMENT_CANDIDATE_EXPIRED` | 409 | The uploaded document expired; upload it again |
| `DOCUMENT_SET_INCONSISTENT` | 409 | The documents are in an inconsistent state; contact support |
| `MULTI_DOCUMENT_REPLACE_UNSUPPORTED` | 409 | An inline document replacement that a multi-document set does not support; use the `/documents` routes |
| `SIGNED_DATA_IMMUTABLE` | 409 | Data that has already been signed cannot be changed |
| `SEND_EFFECTS_EXIST` | 409 | Sending has already started and cannot be undone |
| `SEND_IN_PROGRESS` | 409 | A send of this signing request is in progress |

The `MultiDocumentErrorCode` schema in the API reference lists all 42 codes that the multi-document routes and the routes they change can return. A server fault returns `500` with `INTERNAL_ERROR` or `INTERNAL`, depending on the route (the `/documents` routes use `INTERNAL`); neither carries detail.

### Participant order

Signers, approvers, and organization seal participants share one order space. CC recipients are stored separately and never take a position in it.

* `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` move a recipient or seal participant by shift-insert: every participant between the old and new positions is renumbered. A target position above `n` returns `400 INVALID_SIGNING_ORDER`. An `order` below 1 returns `400 INVALID_SIGNING_ORDER` for a recipient and `400 VALIDATION_ERROR` for a seal participant.
* A new Signer or Approver on those routes is inserted at `order` within `[1..n+1]`, or appended when `order` is omitted. `order: 0` or a position outside that range returns `400 INVALID_SIGNING_ORDER`.
* A new seal participant requires `order` as a positive integer. A missing or zero `order` returns `400 VALIDATION_ERROR`; a position outside `[1..n+1]` returns `400 INVALID_SIGNING_ORDER`.
* On `PATCH /templates/{id}` and `PATCH /signing-requests/{id}`, the seal must belong to your company: another company's seal returns `404 NOT_FOUND`. A revoked, deleted, or superseded seal returns `400 SEAL_UNAVAILABLE`. A seal scoped to another workspace returns `400 SEAL_UNAVAILABLE` on `PATCH /signing-requests/{id}`. On `PATCH /templates/{id}` it returns `404 NOT_FOUND` when you add a seal participant or move one (`order` set); changing only the seal of an existing participant (`id` and `seal_id`, no `order`) does not check the seal's workspace.
* On a sent signing request, `PATCH /signing-requests/{id}` returns `409 ALREADY_SENT`, except a protected caller's swap of a paused seal participant. Removing a seal participant with `DELETE /signing-requests/{id}/seal-participants/{participant_id}` returns `409 SEAL_MUTATION_NOT_ALLOWED`.
* An order change that conflicts with a seal participant that has already been applied returns `409 SIGNING_ORDER_LOCKED_APPLIED`.
* `POST /signing-requests` and `POST /signing-requests/create-and-send` without seals number recipients in array order when `use_signing_order` is false or any recipient omits `order`. With seals, every recipient needs an `order`, and recipients and seals together must form `1..n`: a missing order or a gap returns `400 INVALID_SIGNING_ORDER`, and two participants (recipients or seals) on the same order return `400 SEAL_ORDER_COLLISION`.
* `PUT /templates/{id}` applies each entry of `users` and `deleted_users` as its own participant write. If one entry fails, the entries applied before it are kept.
* `POST /templates/{id}/copy` keeps the source template's order, drops seal participants whose seal is not in scope for the target workspace (along with their fields), and compacts the remaining participants to `[1..n]`.

### Organization seal authority name

Seals returned by `POST /seals`, `GET /seals`, `GET /seals/{id}`, and `PATCH /seals/{id}` include `authority_name`, the name the seal was attested for: the company for company scope or the protected workspace, otherwise the workspace. It is `null` for seals whose lineage was created before the name was pinned; those seals certify in the company's current name.

### Other changes

* `POST /signing-requests/{id}/resend` returns `409 SEND_IN_PROGRESS` while a send of that signing request is in progress.
* Fixed: for companies enabled for multi-document signing, creating a signing request (`POST /signing-requests`) and creating and sending one (`POST /signing-requests/create-and-send`) now return each organization seal participant with its seal (id, lineage, version, name and display name) in `seal_participants`. Previously this list was empty, even though the seal itself was saved and applied correctly on the document. Signed documents, certificates and webhooks are not affected.
* Documentation only: the `POST /signing-requests/create-and-send` response now documents `seal_participants`, which it already returned. The resend response now documents `recipients_suppressed`, the number of recipients not reminded because their address is suppressed.

### Unchanged

* `PUT /signing-requests/{id}` with a field id that does not belong to the signing request still returns `400`, on multi-document requests too.
* `reminders` on `POST /signing-requests/create-and-send` work as before, including on requests created with `document_ids`.

### Migration notes

* The change is additive. Requests that never use `document_ids`, `document_index`, or the `/documents` routes behave as before, and companies that are not enabled see no new response keys.
* If you generate a client from the OpenAPI spec: `document` is optional on `POST /templates`, and the seal participant schema in signing-request responses is now named `SealParticipantApi` (previously `SealParticipant`).
* If you parse error codes strictly, accept the new codes above.
* On an enabled company, send `documents_layout_version` with field writes on templates and signing requests that have more than one document.

***

## v1.38.0

**Release Date:** September 17, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.38.0 spec](/api-reference/v01.38.00/openapi-v01.38.00.json)

### Catalan support

The supported language set grows from 14 to 15 with the addition of Catalan (`ca`), joining `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, and `nb`.

The new code is accepted at every language-bearing surface of the API:

* **Workspace settings**: `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings**: `language` on the company settings endpoints
* **Per-signing-request email language**: the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms**: the `{language}` path parameter on the company and workspace signer-terms endpoints (`PUT` / `DELETE`)
* **Email template defaults**: `GET /email-templates/defaults/{language}`
* **Organization seal statement**: `statement.language` on seal creation and update, returned as `statement_language` on the seal

Setting Catalan localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, and date formatting. The completion certificate follows the workspace language, so set Catalan on the workspace for a Catalan certificate.

Validation errors for unsupported codes now list all 15 languages.

#### Migration notes

* The API change is additive. The existing 14 language codes are accepted and returned exactly as before, and requests that never send `ca` validate as before.
* Unless the signing URL carries a supported `lang` code, the signing page selects the first language in the signer's browser preference list that Firma.dev supports. A signer whose browser lists `ca` or a `ca-` regional tag ahead of every other supported language now sees the signing page in Catalan. Before v1.38.0, the signer saw the next supported language in the list or English. Signing links sent by email do not include a `lang` parameter, so this behavior also applies to existing signers. A supported `lang` code you add to an embedded signing URL still sets the language; any other value is ignored.
* The consent statement resolves in this order: workspace terms in the signer's language, company terms in the signer's language, workspace terms in the workspace's configured language, company terms in the company's configured language, then Firma.dev's default terms in the signer's language. If no Catalan terms or terms in the applicable configured language exist, a Catalan-first signer now accepts Firma.dev's default Catalan statement instead of custom terms in another browser language, such as Spanish. Terms in the workspace's or company's configured language still apply when available.
* Add Catalan signer terms at the company or workspace level to keep custom terms for these signers. Use `PUT /company/signer-terms/ca`, `PUT /workspace/{workspace_id}/signer-terms/ca`, or the dashboard terms settings.

***

## v1.37.1

**Release Date:** September 15, 2026

**Release Type:** Patch Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json) (unchanged in this release)

### CC recipients

The update endpoints now store recipients with `"designation": "CC"`, and the read endpoints now return them. Before this release they did neither.

#### Adding and updating CC recipients

* `PUT /templates/{id}` (`users[]`) and `PATCH /templates/{id}` (`user`) store CC recipients. Previously these returned `400` and `500`.
* `PUT /signing-requests/{id}` (`recipients[]`) and `PATCH /signing-requests/{id}` (`recipient`) store CC recipients. Previously `PUT` returned `200` and counted the CC in `summary.recipients_created` without storing it, and `PATCH` returned `500`.
* On `PUT /signing-requests/{id}`, a recipient that fails to save is now listed in `details.recipients` of the `400` response instead of being counted in `summary.recipients_created`.
* Existing CC recipients can be updated by `id` and removed through `deleted_users` / `deleted_recipients`, the same way as signers and approvers.
* `first_name` and `email` are required for a new CC recipient.
* `designation` is matched case-insensitively (`"CC"`, `"cc"`).

#### CC recipients in responses

CC recipients are returned with `"designation": "CC"`, after signers and approvers, by:

* `GET /signing-requests/{id}/users`
* `GET /templates/{id}/users`
* `GET /templates/{id}` and `GET /templates` (`recipients`)
* the `recipients` array of the `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PUT /signing-requests/{id}` responses

CC entries carry the same keys as the other entries on that endpoint. They never get a signing link, and keys that only apply to signing hold neutral values (for example `required_fields: []` and `ready_to_send: true`).

#### Template-based creation

* `POST /signing-requests` and `POST /signing-requests/create-and-send` with `template_id` now copy the template's CC recipients to the new signing request. A template CC is skipped when a CC with the same email (case-insensitive) is already on the request.
* A request-body recipient with `"designation": "CC"` is always added as a CC recipient. It is never matched to a template user by `template_user_id` or `order`.

#### Validation

* Changing an existing recipient between CC and Signer or Approver returns `400`. `PATCH /templates/{id}` and `PATCH /signing-requests/{id}` return the message `Cannot change designation between CC and Signer/Approver; delete the recipient and create it again`, `PUT /signing-requests/{id}` lists it in `details.recipients`, and `PUT /templates/{id}` returns the generic `Validation errors occurred`. Delete the recipient and create it again with the new designation.
* A field cannot be assigned to a CC recipient. On `PUT /signing-requests/{id}`, including for a CC created in the same request through `_temp_id`, the field error reads `Cannot assign fields to CC recipient.`; other field paths reject a CC id as an invalid recipient.
* Updating or deleting a recipient by `id` now only matches recipients that have not been deleted. An already-deleted recipient is treated as not found instead of being written to.

#### Migration notes

* No new endpoints, fields, or enum values, so the v1.37.0 spec still applies.
* Recipient lists can now include CC entries. If your code treats every entry as a signer, check `designation`.
* Signing requests created from a template that has CC recipients now include those CC recipients, and they receive the completed document. Remove the CC recipients from the template if you do not want this.
* If you relied on `PUT /signing-requests/{id}` returning `200` when a recipient failed to save, handle the `400` response.

***

## v1.37.0

**Release Date:** September 14, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.37.0 spec](/api-reference/v01.37.00/openapi-v01.37.00.json)

### Organization Seals

Electronic seals applied automatically on behalf of a company, as participants in the signing order. Setup, scope rules, and certificate output are described in the [Organization Seals guide](/guides/organization-seals).

#### New endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/seals` | Create a seal (`kind`: `uploaded`, `typed`, or `drawn`; `scope`: `company` or `workspace` with `workspace_id`). Requires a protected API key for company scope |
| `GET` | `/seals` | List seals visible in the key's scope |
| `GET` | `/seals/{id}` | Get one seal |
| `PATCH` | `/seals/{id}` | Replace the image (new version), rename, update `display_name` / `signatory_title`, or set `is_default` |
| `DELETE` | `/seals/{id}` | Revoke; add `?stop_pending=true` to pause in-flight participants |
| `GET` | `/seals/{id}/image` | Canonical PNG; every read is logged |
| `GET` | `/seals/{id}/applications` | Signing requests the seal was applied to |
| `GET` | `/seals/{id}/access-log` | Lifecycle and image-read events |
| `DELETE` | `/seals/{id}/erase` | Erase a revoked lineage that no request or template references, 90 days after revocation |
| `DELETE` | `/signing-requests/{id}/seal-participants/{participant_id}` | Remove a seal participant and its fields from an unsent request |

#### Seal participants

Signing requests and templates accept a `seal_participants[]` array alongside `recipients[]` / `users[]` on `POST /signing-requests`, `POST /signing-requests/create-and-send`, `PATCH /signing-requests/{id}`, `POST /templates`, and `PATCH /templates/{id}`. Each entry takes `temp_id` (client id used to assign fields), `seal_id`, and `order`. Recipients and seals share one contiguous order space; order 1 applies at send.

Fields owned by a seal set `seal_participant_temp_id` instead of a recipient. Seal fields are server-authored (`read_only: 1`, no recipient) and client-provided values on them are ignored. Signing-request responses now include `seal_participants[]`.

#### Seal swap

`PATCH /signing-requests/{id}` accepts `seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" }` to move a paused participant on a sent request to a different in-scope seal. Requires a protected API key.

#### Webhook events

| Event | Trigger |
| - | - |
| `organization_seal.created` | Seal created |
| `organization_seal.updated` | Image replaced (new version), renamed, or default flag changed |
| `organization_seal.deleted` | Seal revoked |
| `organization_seal.erased` | Revoked lineage permanently erased |
| `signing_request.seal.applied` | Seal applied to a document |
| `signing_request.seal.paused` | Seal participant paused (revoked with stop pending, or integrity mismatch) |
| `signing_request.seal.swapped` | Paused participant swapped to a different seal |

#### Error codes

`SEALS_DISABLED`, `SEAL_NOT_FOUND`, `SEAL_SCOPE_FORBIDDEN`, `SEAL_IMAGE_INVALID`, `SEAL_ALREADY_REVOKED`, `SEAL_ERASE_NOT_ELIGIBLE`, `SEAL_MUTATION_NOT_ALLOWED`, `SEAL_ORDER_COLLISION`, `SEAL_PAUSED`, `SEAL_UNAVAILABLE`, and `SEAL_CREATION_DISABLED_EDGE` (reserved for the edge fallback host; the primary API host performs seal creation).

#### Migration notes

* Purely additive. `recipients[]`, `users[]`, and all existing endpoints are unchanged.
* No breaking changes.

***

## v1.36.0

**Release Date:** August 31, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.36.0 spec](/api-reference/v01.36.00/openapi-v01.36.00.json)

### Anchor tags

* `add_white_background` on anchor tag definitions draws a white background across the full resolved field rectangle, independently of anchor-text removal.

### Error responses

* Error objects carry a machine-readable `code`.
* Validation failures also return `errors[]` with every error when multiple failures are reported together; the top-level error repeats the first item for backward compatibility.

### Create and send

* `POST /signing-requests/create-and-send` responses include `warnings[]`: optional non-blocking warnings, including unknown anchor-tag properties during the compatibility window and anchor-processing warnings.

#### Migration notes

* Purely additive. No breaking changes.

***

## v1.35.0

**Release Date:** August 13, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.35.0 spec](/api-reference/v01.35.00/openapi-v01.35.00.json)

### Cross-workspace template copy

New endpoint `POST /templates/{id}/copy` deep-copies a template to another workspace within the same company. All child data is copied with correct ID remapping:

* Template settings (expiration, signing order, email flags, completion page, etc.)
* Recipients (signers, approvers) with designation preserved
* Fields with `required_conditions` and `visibility_conditions` field references remapped
* CC recipients
* Custom field definitions
* Reminders with recipient references remapped
* PDF document (independently stored copy)

**Request body:**

* `workspace_id` (required, uuid) - target workspace to copy the template into
* `name` (optional, string, max 255) - name for the copy (defaults to original name with " (copy)" suffix)

**Authorization:** requires a company-level (protected) API key. Workspace-scoped keys receive `403 PROTECTED_KEY_REQUIRED`.

**New endpoint:**

* `POST /templates/{id}/copy` - copy template to another workspace

***

## v1.34.0

**Release Date:** August 7, 2026

**Release Type:** Minor Release

**OpenAPI Spec:** [Download v1.34.0 spec](/api-reference/v01.34.00/openapi-v01.34.00.json)

### Completion page customization

Four new nullable fields on signing requests, templates, workspace settings, and company settings control what signers see after completing their signature:

* `completion_title` (string, max 200 chars) - custom heading on the completion page
* `completion_message` (string, max 1000 chars) - custom body text
* `completion_redirect_url` (string, max 2000 chars, https only) - URL to redirect signers to after signing
* `completion_redirect_delay` (integer, 0-30) - seconds before redirect (defaults to 5 when a URL is set)

Settings cascade from company to workspace to template to signing request. Each level can override the parent, and each field resolves independently. Setting a field to `null` (or omitting it) inherits from the parent level; the built-in translated completion page is the final fallback.

**Affected endpoints:**

* `POST /signing-requests` - accepts completion fields
* `POST /signing-requests/create-and-send` - accepts completion fields
* `PUT /signing-requests/{id}` - accepts completion fields
* `PATCH /signing-requests/{id}` - accepts completion fields
* `GET /signing-requests/{id}` - returns completion fields
* `POST /templates` - accepts completion fields
* `PUT /templates/{id}` - accepts completion fields
* `PATCH /templates/{id}` - accepts completion fields
* `GET /templates/{id}` - returns completion fields
* `PUT /workspace/{id}/settings` - accepts completion fields
* `GET /workspace/{id}/settings` - returns completion fields
* `PUT /company/settings` - accepts completion fields
* `GET /company/settings` - returns completion fields

**Validation:**

* `completion_redirect_url` must use `https://`. For test-mode signing requests (`is_test: true`), `http://localhost` and `http://127.0.0.1` are also accepted.
* Redirect is time-limited: the auto-redirect only fires within 10 minutes of signing completion. After that, the custom title and message still display but no redirect occurs.

### Migration guide

No breaking changes. All new fields are nullable and default to `null`. Existing signing requests, templates, and settings are unaffected - the completion page renders its built-in translated content when no custom settings are configured.

***

## v1.33.0

**Release type:** Minor Release

**Released:** 2026-08-03

[Download OpenAPI Spec](/api-reference/v01.33.00/openapi-v01.33.00.json)

### Five new languages

The supported language set grows from 9 to 14: Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`.

The new codes are accepted at every language-bearing surface of the API:

* **Workspace settings** — `language` on `PUT /workspace/{workspace_id}/settings` (and returned by the corresponding GET)
* **Company settings** — `language` on the company settings endpoints
* **Per-signing-request email language** — the `language` field on `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`
* **Signer terms** — the `{language}` path parameter on the company and workspace signer-terms endpoints (`GET` / `PUT` / `DELETE`)
* **Email template defaults** — `GET /email-templates/defaults/{language}`

Setting one of the new languages localizes the full signer experience: signer-facing emails, the signing ceremony UI, the consent statement recorded at terms acceptance, date formatting, and the completion certificate (including correct rendering of Czech and Romanian diacritics).

Validation errors for unsupported codes now list all 14 languages.

### Migration Guide

No action required. The change is purely additive — the existing 9 language codes behave exactly as before, and workspaces or signing requests that never set a language are unaffected.

***

## v1.32.0

**Release type:** Minor Release

**Released:** 2026-07-22

[Download OpenAPI Spec](/api-reference/v01.32.00/openapi-v01.32.00.json)

### Explicit field font size

Text-bearing fields (`text`, `textarea`, `email`, `name`, `phone`, `company`, `title`, `number`, `date`, `signing_date`, `approval_date`, `dropdown`, `url`) now accept an optional `fontSize` inside `format_rules` — an integer between 8 and 48, in pixels. See the new `TextFormatRules` schema; `DateFormatRules` gains the same optional property, so a date field can carry both `dateFormat` and `fontSize`.

The value is a **starting/maximum** size, not a guarantee: the signing view and the sealed PDF both start rendering the field value at the explicit size and still auto-shrink it to fit the field box when the content overflows. Omit the property for automatic sizing (the previous behavior, unchanged). Out-of-range values are clamped to 8-48; non-numeric values are ignored. Signature, initials, checkbox, radio, file, and stamp fields do not accept a font size.

Set it wherever `format_rules` is accepted — template field create/update and signing-request field payloads — for example:

```json theme={null}
{ "format_rules": { "fontSize": 12 } }
```

### Anchor tags: `font_size`

Anchor tags gain an optional `font_size` property (integer, 8-48). When an anchor resolves to a field, the value is stored on the created field as `format_rules.fontSize` and behaves exactly as above.

### Migration Guide

No action required. The properties are optional and additive — fields without `fontSize` render exactly as before, and existing templates and signing requests are unaffected.

***

## v1.31.0

**Release type:** Minor Release

**Released:** 2026-07-14

[Download OpenAPI Spec](/api-reference/v01.31.00/openapi-v01.31.00.json)

### Opt-in signing-request email language

New optional `language` field on the signing-request create and update endpoints — `POST /signing-requests`, `POST /signing-requests/create-and-send`, and `PATCH` / `PUT /signing-requests/{id}`. Set it to one of `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, and every signer-facing email for that signing request — invitation, reminders, OTP verification, completion and CC, expiry, cancellation, and decline — along with its date formatting, uses that language.

The field is nullable and additive: `language` controls the signer-facing **emails** for the whole request.

### Migration Guide

No action required. The field is optional — omit it or send `null` and behavior is unchanged: emails fall back to the workspace language, then the company language, then `en`. Existing signing requests are unaffected.

***

## v1.30.0

**Release type:** Minor Release

**Released:** 2026-07-08

[Download OpenAPI Spec](/api-reference/v01.30.00/openapi-v01.30.00.json)

### Retrieve signer marks as images

Four new read-only endpoints return a signer's captured marks individually, separate from the signed PDF:

* `GET /signing-requests/{id}/signers/{signer_id}/signature` — the signer's adopted signature
* `GET /signing-requests/{id}/signers/{signer_id}/initials` — the signer's adopted initials
* `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}` — a stamp for a specific stamp field
* `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}` — a file the signer uploaded to a file field

The signature, initials, and stamp endpoints return the mark as a base64 PNG data URI (`data:image/png;base64,...`), usable directly in an `<img src>`. The file endpoint returns a short-lived (300 second) pre-signed download URL. A signer adopts one signature and one initials, applied to all their fields of that type, so those endpoints take no `field_id`; stamps and files are per-field and require `field_id` (obtain field IDs from `GET /signing-requests/{id}/fields`).

By default a signer-ID frame is overlaid on returned images; pass `include_frame=false` for the bare mark. These endpoints are rate limited to 60 requests per minute. The legal validity of a signature rests on the sealed PDF and its completion certificate, not on a retrieved image.

### Migration Guide

No breaking changes. These are new additive endpoints; existing integrations require no changes.

***

## v1.29.0

**Release type:** Minor Release

**Released:** 2026-07-06

[Download OpenAPI Spec](/api-reference/v01.29.00/openapi-v01.29.00.json)

### Two-step document upload

A new `POST /documents` endpoint enables uploading documents larger than the inline request size limit. Instead of sending a base64-encoded document in the request body, you can now:

1. Call `POST /documents` with the file metadata to receive a presigned upload URL
2. `PUT` the raw file bytes directly to the upload URL (supports up to 50MB)
3. Pass the returned `document_id` in your `POST /signing-requests` or `POST /signing-requests/create-and-send` request

This is required for documents larger than approximately 5MB. Smaller documents can continue using the inline `document` field.

### New request field: `document_id`

The `POST /signing-requests/create-and-send` endpoint now accepts `document_id` as an alternative to `document` and `template_id`. All three fields are mutually exclusive - provide exactly one.

### Document size limit increase

The maximum document size has been increased from 20MB to 50MB when using the two-step upload flow.

### Migration Guide

No breaking changes. Existing integrations using inline `document` or `template_id` continue to work unchanged. To upload larger documents, adopt the two-step flow via `POST /documents`.

***

## v1.28.0

**Release type:** Minor Release

**Released:** 2026-07-05

[Download OpenAPI Spec](/api-reference/v01.28.00/openapi-v01.28.00.json)

### TypeScript SDK code samples

Every endpoint in the API reference now includes a copy-paste code sample for the official [`@firma-dev/sdk`](/guides/typescript-sdk) TypeScript client, showing the exact typed call for that operation. See the new [TypeScript SDK guide](/guides/typescript-sdk) to install the client and get started.

### Reference surface changes

The following endpoints were removed from the API reference because they are not part of the documented partner API surface:

| Endpoint | Notes |
| - | - |
| `POST /save-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). Embedded signing is documented under the [Embeddables](/guides/embeddable-signing) guides. |
| `POST /send-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `GET /get-embedded-signing-request` | Embedded editor endpoint (JWT-authenticated). |
| `POST /documents` | Legacy document endpoint, superseded by the template and signing request endpoints. |

### Migration Guide

No changes are required for integrations using the partner API endpoints documented here. If you were referencing the embedded signing-request endpoints, use the [Embeddables](/guides/embeddable-signing) guides instead; the embedded editor continues to rely on those endpoints. If you were using the legacy `/documents` endpoints, migrate to the template (`POST /templates`) and signing request (`POST /signing-requests`) endpoints.

***

## v1.27.0

**Release type:** Patch Release

**Released:** 2026-06-29

[Download OpenAPI Spec](/api-reference/v01.27.00/openapi-v01.27.00.json)

### Settings fields now documented in responses

This release documents settings fields that the API already returns. All changes are additive and backward-compatible — no API behavior changed, only the OpenAPI specification was updated to match what the endpoints already send.

#### Signing request settings

The settings object returned by the signing request endpoints (`POST /signing-requests`, `POST /signing-requests/create-and-send`, `GET /signing-requests`, `GET /signing-requests/{id}`, `PUT /signing-requests/{id}`, `PATCH /signing-requests/{id}`) now documents four additional fields:

| Field | Type | Description |
| - | - | - |
| `show_qr_code` | boolean or null | Show a QR code on the signing page that lets signers continue on their phone. Inherits from the workspace or company setting when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from the workspace or company setting when `null`. |
| `identity_editable_fields` | string\[] or null | Identity fields signers may edit before signing (e.g. `["name", "company"]`). `null` disables identity editing. |
| `notify_identity_change_email` | boolean | Send an email notification when a signer changes their identity. |

#### Template settings

The settings object returned by the template endpoints (`POST /templates`, `PUT /templates/{id}`, `PATCH /templates/{id}`, `GET /templates`, `GET /templates/{id}`, `POST /templates/{id}/replace-document`) now documents the `show_qr_code` field. Template settings cover the same options as signing request settings except the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests.

#### Cancel and resend responses

| Endpoint | New response field | Type | Description |
| - | - | - | - |
| `POST /signing-requests/{id}/cancel` | `emails_sent` | integer | Number of cancellation notification emails sent to signers |
| `POST /signing-requests/{id}/resend` | `recipients_failed` | integer | Number of recipients whose resend notification failed to send |

### New schemas

Two new schemas split the settings shapes that differ across endpoints, so each response documents exactly the fields it returns:

| Schema | Description |
| - | - |
| `TemplateSettings` | Settings returned by the template endpoints. Matches `SigningRequestSettings` minus the signer-identity fields (`identity_editable_fields`, `notify_identity_change_email`), which apply only to signing requests. |
| `LegacyDocumentSettings` | Reduced settings set returned by the deprecated `POST /documents` endpoint. New integrations should use the signing request endpoints, which return `SigningRequestSettings`. |

### Migration Guide

No breaking changes. These are documentation-only additions describing fields the API already returns. Existing integrations are unaffected. If you parse settings objects, you can now rely on the documented `show_qr_code`, `allow_presigning_download`, `identity_editable_fields`, and `notify_identity_change_email` fields, and on `emails_sent` / `recipients_failed` in cancel and resend responses.

***

## v1.26.0

**Release type:** Minor Release

**Released:** 2026-06-23

[Download OpenAPI Spec](/api-reference/v01.26.00/openapi-v01.26.00.json)

### Workspace settings: four new fields

Four fields are now available on `GET /workspace/{workspace_id}/settings` and `PUT /workspace/{workspace_id}/settings`:

| Field | Type | Description |
| - | - | - |
| `signing_button_label_overrides` | object or null | Per-language custom labels for signing view buttons. Keys are language codes, values are objects mapping button keys to custom text. Set to `null` to use defaults. |
| `show_qr_code` | boolean or null | Show a QR code on the signing page so signers can continue on their phone. Inherits from company settings when `null`. |
| `allow_presigning_download` | boolean or null | Allow signers to download the original document before signing. Inherits from company settings when `null`. |
| `show_partial_watermark` | boolean or null | Show an IN PROGRESS watermark on partial PDF downloads. Inherits from company settings when `null`. |

#### Button label overrides structure

```json theme={null}
{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}
```

Customizable button keys: `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, `signing.decline.confirm`, `signing.decline.title`, `signing.decline.cancel`, `signing.finishAnyway`, `signing.goBack`.

Values are sanitized server-side (HTML stripped, max 200 characters). Empty or whitespace-only values are ignored.

***

## v1.25.2

**Release type:** Patch Release

**Released:** 2026-06-18

[Download OpenAPI Spec](/api-reference/v01.25.02/openapi-v01.25.02.json)

### Stricter validation for template field overrides

When creating a signing request from a template, any provided field that does not match a field in that template is now rejected with **`400` `VALIDATION_ERROR`** instead of being silently ignored. Previously such a field was dropped and the request still succeeded, so a mistyped identifier meant the field simply never appeared on the document with no error.

A provided field matches a template field by `template_field_id`, `variable_name`, or `variable_defined_name`. The error names the offending field(s):

```json theme={null}
{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}
```

Applies to `POST /signing-requests` and `POST /signing-requests/create-and-send`.

**Migration:** ensure every field you send on a template-based create references an existing template field. If you were relying on extra/unmatched fields being ignored, remove them.

### Case-insensitive field types

Field `type` values are now normalized case-insensitively. `"Initials"`, `"Signature"`, `"TextArea"`, etc. resolve to their canonical type (`initial`, `signature`, `text_area`) instead of being rejected as invalid. Lowercase values are unchanged.

## v1.25.1

**Release type:** Patch Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.01/openapi-v01.25.01.json)

### Accurate error responses for create-and-send

`POST /signing-requests/create-and-send` previously returned a generic **500** whenever the send step rejected a request, hiding the real reason. It now returns the **client-actionable status** (`400`, `402`, or `422`) with a machine-readable `code` and the relevant detail:

* **`400` `VALIDATION_ERROR`** — request or send validation failed (e.g. a signer missing required information); the response includes `validation_errors`, `field_errors`, or `details` identifying what to fix.
* **`402` `INSUFFICIENT_CREDITS`** — not enough credits to send; `current_credits` reports the balance.
* **`422` `RECIPIENT_EMAIL_SUPPRESSED`** *(new)* — a recipient's email address is suppressed (previously bounced or marked as spam) and cannot be sent to.

Genuine server-side failures still return `500`. When the send step fails, the partially-created signing request is rolled back, so no orphaned draft is left behind.

**Migration guide:** No action required for clients that already treat any non-2xx response as a failure. If you previously special-cased the opaque `500` from this endpoint, switch to branching on the HTTP status / `code`: `400` and `422` mean "fix the request, then retry," `402` means "add credits."

***

## v1.25.0

**Release type:** Minor Release

**Released:** 2026-06-14

[Download OpenAPI Spec](/api-reference/v01.25.00/openapi-v01.25.00.json)

### Editor Brand Colors

The appearance settings now include five additional brand colors that theme the **embedded editors** (the template and signing-request editors you embed on your own pages):

* **`color_accent`** — accent color for highlights, active tabs, switches, and primary controls in the editor chrome.
* **`color_accent_fg`** — foreground (text/icon) color shown on accent surfaces.
* **`color_canvas`** — the document-canvas surround color behind the page.
* **`color_muted`** — muted surface color (separators, hover states, switch tracks).
* **`color_muted_fg`** — muted text color.

These join the existing six color fields, so settings endpoints now carry eleven `color_*` fields:

* **`GET`/`PUT /company/settings`** and **`GET`/`PUT /workspace/{workspace_id}/settings`** accept and return all five new fields. Each is a nullable `#rrggbb` hex string; `null` means inherit (workspace → company → Firma default).
* The resolved **`color_palette`** object returned in embedded-editor payloads now contains eleven keys (the six existing plus `accent`, `accent_fg`, `canvas`, `muted`, `muted_fg`). When unset, `muted` defaults to the resolved `card` color and `muted_fg` is derived for readability, so the palette is always fully populated.

Workspace values override company values; unset values fall back to the Firma defaults, so existing integrations render unchanged.

**Migration guide:** No action required. All five fields are additive and nullable. To brand the embedded editors, send any of the new `color_*` fields (valid `#rrggbb` hex, or `null` to clear) to the company- or workspace-settings endpoint.

***

## v1.24.0

**Release type:** Minor Release

**Released:** 2026-06-09

[Download OpenAPI Spec](/api-reference/v01.24.00/openapi-v01.24.00.json)

### Workspace Test API Keys

Workspaces now expose a **test-mode API key** alongside the existing live key. Requests authenticated with a test key do not consume credits and produce test-flagged, watermarked signing requests.

* **`POST /workspaces`** now provisions a live + test key pair and returns both `api_key` (live) and the new `test_api_key` field.
* **`GET /workspaces/{id}`** and **`GET /workspaces`** now return both `api_key` and `test_api_key`.
* **`POST /workspaces/{id}/api-key/regenerate`** and **`/api-key/expire`** accept an optional `key_type` (`"live"` or `"test"`, default `"live"`). Regenerating one key type no longer affects the other.
* Existing workspaces created via the API are backfilled with a test key.

All changes are additive and backward-compatible: consumers that read `api_key` continue to work unchanged.

**Migration guide:** No action required. To use test mode, read `test_api_key` from any workspace create/get response and send it as the `Authorization` key for requests you want to run in test mode.

***

## v1.23.0

**Release type:** Minor Release

**Released:** 2026-06-04

[Download OpenAPI Spec](/api-reference/v01.23.00/openapi-v01.23.00.json)

### Signer Terms

New Signer Terms endpoints let you manage custom signer consent statements at the company and workspace levels:

* `GET` endpoints list company and workspace signer terms
* `PUT` endpoints create or update per-language company and workspace signer terms
* `DELETE` endpoints remove company and workspace signer terms

### Company Settings

New `GET /company/settings` and `PUT /company/settings` endpoints expose company settings, including the terms acceptance gate.

### Schema Changes

* **Company settings** schema: added `require_terms_acceptance` (boolean)
* **Workspace settings** schema: added `require_terms_acceptance` (boolean, nullable). Use `null` to inherit the company setting.

### Migration Guide

No breaking changes. This release is additive, and no action is required for existing integrations.

***

## v1.22.1

**Release type:** Patch Release

**Released:** 2026-06-02

[Download OpenAPI Spec](/api-reference/v01.22.01/openapi-v01.22.01.json)

### Email Domain Deletion

`DELETE /company/domains/{id}` and `DELETE /workspace/{workspace_id}/domains/{id}` now succeed when the target is the workspace's primary domain or its only domain. Previously these returned `400 "Cannot delete primary domain"`. After deletion, outbound email falls back to the company default sender, or the platform default if none is set. To use a custom sending domain again, add and verify a new domain, then set it as primary.

### Migration Guide

No breaking changes. The `400 "Cannot delete primary domain"` and "cannot delete the only domain" responses are removed from both `DELETE` domain endpoints; they now return `200` in those cases. Integrations that special-cased that `400` can drop the handling.

***

## v1.22.0

**Release type:** Minor Release

**Released:** 2026-05-30

[Download OpenAPI Spec](/api-reference/v01.22.00/openapi-v01.22.00.json)

### Delete Signing Request Endpoint

New `DELETE /signing-requests/{id}` endpoint for removing unsent (draft) signing requests. This endpoint only works on signing requests that have not been sent yet. For sent signing requests, use the existing cancel endpoint instead.

**Response:**

* `200` with `signing_request_id` and `deleted_on` on success
* `409 ALREADY_SENT` if the signing request has been sent
* `404` if not found or already deleted

### New Webhook Event

* `signing_request.deleted` fires when a signing request is deleted via the API

### Migration Guide

No breaking changes. The new `DELETE` method on `/signing-requests/{id}` is purely additive. Existing integrations are unaffected.

***

## v1.21.1

**Release type:** Patch Release

**Released:** 2026-05-19

[Download OpenAPI Spec](/api-reference/v01.21.01/openapi-v01.21.01.json)

### Workspace Webhook Management

The `PATCH /workspaces/{id}` endpoint now supports two new fields for managing workspace-level webhooks via the API:

* `webhook_enabled` (boolean) - Enable or disable workspace-level webhooks. When set to `true` for the first time, a webhook secret is automatically generated.
* `ignore_company_webhooks` (boolean) - If `true`, company-level webhooks will not fire for events in this workspace.

Previously, these settings could only be configured through the dashboard UI.

### Schema Changes

* **PATCH /workspaces/** request body: added `webhook_enabled` (boolean, optional) and `ignore_company_webhooks` (boolean, optional)
* **PATCH /workspaces/** response: now includes `webhook_enabled`, `webhook_secret`, `webhook_secret_rotated_at`, `webhook_secret_created_at`, and `ignore_company_webhooks`

### Migration Guide

No breaking changes. Existing workspace webhook configurations are unaffected. Use `PATCH /workspaces/{id}` with `webhook_enabled: true` to enable workspace webhooks via API instead of the dashboard.

***

## v1.21.0

**Release type:** Minor Release

**Released:** 2026-05-14

[Download OpenAPI Spec](/api-reference/v01.21.00/openapi-v01.21.00.json)

### New Settings

* `email_local_part` (string, nullable) - Customize the local-part (before the @) of outgoing signing emails when using a verified custom domain. Available at two levels:
  * **Company settings** (`GET/PATCH /company`) - Sets the default for all workspaces. String with default `"support"`.
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Nullable string (null inherits from company).

Emails are sent from `{email_local_part}@{your-custom-domain}`. For example, setting `email_local_part` to `"noreply"` sends emails from `noreply@yourdomain.com` instead of `support@yourdomain.com`.

Validation: lowercase alphanumeric, dots, hyphens, and underscores. Must start and end with an alphanumeric character. 1-64 characters. Pattern: `^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$`

### Schema Changes

* **Company** schema: added `email_local_part` (string, default `"support"`)
* **Workspace settings** schema: added `email_local_part` (string, nullable)

### Migration Guide

No breaking changes. Existing configurations continue to send emails from `support@{domain}` by default. Set `email_local_part` at the company or workspace level to customize the sender address.

***

## v1.20.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Settings

* `disable_guided_navigation` (boolean, nullable) - Disable automatic scrolling to the next required field during signing. Available at four levels:
  * **Company settings** (`GET/PUT /company/settings`) - Sets the default for all workspaces. Boolean (not nullable).
  * **Workspace settings** (`GET/PUT /workspace/{id}/settings`) - Overrides company default. Boolean or null (null inherits from company).
  * **Template** (`POST/PATCH /templates`) - Copied to signing requests created from this template. Boolean or null.
  * **Signing request** (`POST/PATCH /signing-requests`) - Highest priority override. Boolean or null (null inherits from workspace/company).

The setting follows the same cascading pattern as `require_otp_verification`: signing request level takes priority, then workspace, then company settings.

### Schema Changes

* **Company settings** schema: added `disable_guided_navigation` (boolean)
* **Workspace settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Template settings** schema: added `disable_guided_navigation` (boolean, nullable)
* **Signing request settings** schema: added `disable_guided_navigation` (boolean, nullable)

### Migration Guide

No breaking changes. Existing signing requests and templates continue to work as before (auto-scroll enabled by default). To disable auto-scroll, set `disable_guided_navigation: true` at the desired level.

[Download OpenAPI Spec](/api-reference/v01.20.00/openapi-v01.20.00.json)

***

## v1.19.0

**Release type:** Minor Release

**Released:** 2026-05-12

### New Endpoints

* `POST /company/logo` - Upload a company logo image (PNG or JPEG, max 2MB). The logo appears on signing certificates and emails.
* `DELETE /company/logo` - Remove the company logo. Certificates fall back to the Firma default.
* `POST /workspaces/{id}/logo` - Upload a workspace-specific logo that overrides the company logo for that workspace.
* `DELETE /workspaces/{id}/logo` - Remove the workspace logo. Falls back to the company logo.

### Schema Changes

* **Workspace** schema now includes `icon_url` (string, nullable) - a publicly accessible URL to the workspace logo image
* **Company** `icon_url` is now read-only in PATCH/PUT requests. Use the new `POST /company/logo` endpoint to manage logos.

### Migration Guide

* If you were setting `icon_url` directly via `PATCH /company` or `PATCH /workspaces/{id}`, switch to the new `POST .../logo` endpoints instead. The `icon_url` field is no longer accepted in update request bodies.
* `icon_url` in GET responses now returns a publicly accessible URL instead of an internal reference.

[Download OpenAPI Spec](/api-reference/v01.19.00/openapi-v01.19.00.json)

***

## v1.18.0

**Release date:** May 5, 2026

### New Features

#### Identity Editable Fields

Signing requests now support per-field, per-signer identity editing. When configured, signers see a confirmation dialog before signing where they can review and edit specified identity fields (name, company, title, phone, address).

New settings property:

| Property | Type | Default | Description |
| - | - | - | - |
| `identity_editable_fields` | `string[]` or `null` | `null` | Array of identity field keys signers can edit. `null` = disabled. |
| `notify_identity_change_email` | `boolean` | `false` | Send an email when a signer changes their identity |

Valid field keys: `name`, `company`, `title`, `phone`, `address`

Per-recipient override via `identity_editable_fields` on the recipient object:

* `null` - use request default
* `[]` - disabled for this signer
* `["name", "company"]` - custom fields for this signer

Example:

```json theme={null}
{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}
```

In this example, John inherits the request default (name + company editable), while Jane has identity editing explicitly disabled.

New webhook event: `signing_request.recipient.identity_changed` is now available as a standard webhook event. Subscribe to it in your webhook configuration to receive notifications when a signer modifies their identity during signing.

#### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, all fields with `prefilled_data` set were automatically locked as read-only. A new `prefilled_editable` property lets you control this behavior.

When `prefilled_editable` is `true`, the field value is still auto-populated from recipient data, but the signer can modify it during the signing process.

| Property | Type | Default | Description |
| - | - | - | - |
| `prefilled_editable` | `boolean` | `false` | When true, signers can edit prefilled values |

Available on:

* Template fields (`PATCH /templates/{id}`, `PUT /templates/{id}`)
* Signing request fields (`POST /signing-requests`, `POST /signing-requests/create-and-send`)
* Field response objects (`GET /signing-requests/{id}`)

Example - create a signing request with an editable prefilled field:

```json theme={null}
{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}
```

#### Field Value Source Validation

The API now validates that fields use only one value source at a time. Requests that combine `read_only_value`, `prefilled_data`, and explicit `value` on the same field will return a `400 VALIDATION_ERROR`. This enforcement applies to:

* `POST /signing-requests`
* `POST /signing-requests/create-and-send`
* `PATCH /templates/{id}` (field creation and update)
* `PUT /templates/{id}` (field upsert)

#### Value Precedence

When `prefilled_editable` is `true` and both an explicit `value` and `prefilled_data` are set on a field, the explicit value takes precedence over the auto-populated recipient data.

### Migration Guide

No breaking changes. New features are opt-in:

* Identity editing is disabled by default (`identity_editable_fields: null`). Set it to an array of field keys to enable.
* Existing prefilled data fields remain locked (read-only) by default. Set `prefilled_editable: true` in `format_rules` to make them editable.

***

## v1.17.0

**Release date:** April 30, 2026

**[Download OpenAPI Spec](/api-reference/v01.17.00/openapi-v01.17.00.json)**

### New Features

#### Color Customization for Signing Experience

Six new nullable color fields allow you to customize the signing experience appearance at both company and workspace levels. Colors follow a 3-tier cascade: Firma defaults are used unless overridden at the company level, and company colors are used unless overridden at the workspace level.

**New fields on Company (`GET /company`, `PUT /company`, `PATCH /company`):**

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary action color for buttons, links, and accents (#rrggbb hex) |
| `color_primary_fg` | `string \| null` | Text color on primary-colored elements |
| `color_background` | `string \| null` | Page/canvas background color |
| `color_foreground` | `string \| null` | Main text color |
| `color_card` | `string \| null` | Card/panel background color |
| `color_border` | `string \| null` | Border and divider color |

**New fields on Workspace Settings (`GET /workspace/{workspace_id}/settings`, `PUT /workspace/{workspace_id}/settings`):**

The same six fields are available on workspace settings. Set a value to override the company default, or set `null` to inherit from the company.

| Field | Type | Description |
| - | - | - |
| `color_primary` | `string \| null` | Primary color override. Null to inherit from company. |
| `color_primary_fg` | `string \| null` | Primary foreground color override. Null to inherit. |
| `color_background` | `string \| null` | Background color override. Null to inherit. |
| `color_foreground` | `string \| null` | Foreground/text color override. Null to inherit. |
| `color_card` | `string \| null` | Card background color override. Null to inherit. |
| `color_border` | `string \| null` | Border color override. Null to inherit. |

#### ColorPalette Schema

A new `ColorPalette` schema represents the resolved color palette applied to the signing experience. All values are hex color strings (#rrggbb).

| Property | Description |
| - | - |
| `primary` | Primary action color (buttons, links, accents) |
| `primary_fg` | Text color on primary-colored elements |
| `background` | Page/canvas background color |
| `foreground` | Main text color |
| `card` | Card/panel background color |
| `border` | Border and divider color |

### Migration Guide

**From v1.16.0 to v1.17.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* All six color fields default to `null`, which preserves the existing Firma default appearance.
* To customize colors, set hex values on company settings (company-wide defaults) or workspace settings (per-workspace overrides).
* The color cascade is: Firma defaults -> Company overrides -> Workspace overrides. Each level only overrides fields that are explicitly set (non-null).

***

## v1.16.0

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.16.00/openapi-v01.16.00.json)**

### New Features

#### Download Signing Request Document

A new endpoint retrieves a download URL for a signing request's document. For completed signing requests, the URL points to the final signed PDF. For in-progress, cancelled, declined, or expired requests, the URL points to a partial snapshot PDF capturing the document state at the time of the last signer action.

**Endpoint:** `GET /signing-requests/{id}/download`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `status` | `string` | Signing request status: `finished`, `in_progress`, `cancelled`, `declined`, or `expired` |
| `is_partial` | `boolean` | `true` when the document is a partial snapshot (not all signers completed) |
| `download_url` | `string` | Pre-signed URL to the PDF document |
| `generated_at` | `date-time \| null` | When the document was last generated |
| `expires_at` | `date-time` | When the `download_url` expires |

**Behavior by status:**

| Signing Request State | Response |
| - | - |
| Not yet sent | `409 Conflict` — download unavailable |
| Sent, generation in progress | `503 Service Unavailable` with `Retry-After` header |
| Sent, at least one signer completed | `200` with `is_partial: true` |
| Cancelled / Declined / Expired | `200` with `is_partial: true` (snapshot of last known state) |
| Completed (all signers finished) | `200` with `is_partial: false` |

Partial snapshots are generated on demand and cached. The first request may return `503` with a `Retry-After` header while the PDF is being generated — retry after the indicated interval.

**URL expiry:** The `download_url` is a pre-signed URL. Fetch the endpoint again after `expires_at` to get a fresh URL.

#### Partial Download Watermark Setting

A new workspace setting `show_partial_watermark` controls whether partial PDF downloads include an "IN PROGRESS — NOT YET EXECUTED" diagonal watermark. Defaults to disabled. Can be set at the company level (default for all workspaces) or overridden per workspace.

**Endpoint:** `PUT /workspace/{workspace_id}/settings`

| Field | Type | Description |
| - | - | - |
| `show_partial_watermark` | `boolean \| null` | `true` to enable watermark, `false` to disable, `null` to inherit company default |

### Migration Guide

**From v1.15.3 to v1.16.0:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* The download endpoint is purely opt-in. No existing behavior changes.
* Call `GET /signing-requests/{id}/download` — handle `503` with `Retry-After` until the document is ready.

***

## v1.15.3

**Release date:** April 27, 2026

**[Download OpenAPI Spec](/api-reference/v01.15.03/openapi-v01.15.03.json)**

### Clean field aliases for GET /signing-requests//fields

The fields endpoint now returns clean, consistently-named fields alongside the existing database column names:

| New Field | Replaces (Deprecated) | Notes |
| - | - | - |
| `type` | `field_type` | Field type string |
| `recipient_id` | `companies_workspaces_signing_requests_users_id` | Recipient UUID |
| `value` | `final_value` | Signed field value |
| `position.x` | `x_postion` | Fixes typo in original name |
| `position.y` | `y_position` | Nested in position object |
| `position.width` | `width` | Nested in position object |
| `position.height` | `heigh` | Fixes typo in original name |

Additionally, `required`, `read_only`, and `date_signing_default` now return booleans (`true`/`false`) instead of integers (`0`/`1`).

All deprecated fields remain in the response for backward compatibility and will be removed in a future major version.

### Migration guide

Update your field parsing to use the new names. The deprecated names still work:

```json theme={null}
// Before → After
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true
```

***

## v01.15.02

**Release Date:** April 23, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.02/openapi-v01.15.02.json)

### Bug Fixes

#### Create-and-Send Field Types Expanded

The `create-and-send` endpoint's `fields` schema was missing several field types that were already supported by the backend and available via `anchor_tags`. The following types have been added to the `fields.type` enum:

* `dropdown` (with `dropdown_options` property)
* `radio_buttons`
* `text_area`
* `url`
* `file`

These types were already accepted by the API and fully functional. This update aligns the OpenAPI specification with the actual backend behavior.

**Affected endpoint:**

* `POST /signing-requests/create-and-send` -- `fields[].type` enum

***

## v01.15.01

**Release Date:** April 17, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.01/openapi-v01.15.01.json)

### Bug Fixes

#### Language Enum Updated

Added missing `ru` (Russian) and `pl` (Polish) language codes to all language enum fields across the API. These languages were already supported by the platform but were missing from the OpenAPI specification, preventing API users from setting them via documented endpoints.

**Affected endpoints:**

* `PUT /workspace/{workspace_id}/settings` — `language` field
* `PUT /company` and `PATCH /company` — `language` field
* `GET /email-templates/defaults` — `language` query parameter

***

## v01.15.00

**Release Date:** April 16, 2026\
[Download OpenAPI Spec](/api-reference/v01.15.00/openapi-v01.15.00.json)

### New Features

#### Workspace-Scoped Webhooks

Webhooks can now be scoped to individual workspaces instead of applying company-wide. This allows different workspaces to have independent webhook configurations and signing secrets.

* **`workspace_id` parameter on webhook creation** — Pass an optional `workspace_id` when creating a webhook to scope it to a specific workspace. Omitting it creates a company-level webhook (existing behavior).
* **`workspace_id` filter on webhook listing** — Filter the webhook list by workspace. When omitted, only company-level webhooks are returned.
* **`ignore_company_webhooks` workspace field** — Workspaces can opt out of receiving company-level webhook events by setting this flag to `true`.

#### Workspace Webhook Secret Management

Two new endpoints for managing workspace-level webhook signing secrets:

* **`POST /workspaces/{id}/webhooks/rotate-secret`** — Generates a new webhook signing secret for the workspace. The old secret remains valid for a 7-day grace period.
* **`GET /workspaces/{id}/webhooks/secret-status`** — Returns the status of the workspace webhook secret including creation date, rotation date, and grace period information.

#### Workspace Response Webhook Fields

The workspace GET response now includes webhook-related fields:

* `webhook_enabled` — Whether workspace-level webhooks are enabled
* `webhook_secret` — The current webhook signing secret
* `webhook_secret_created_at` — When the current secret was created
* `webhook_secret_rotated_at` — When the secret was last rotated
* `ignore_company_webhooks` — Whether the workspace ignores company-level webhook events

### Changes

* Added optional `workspace_id` parameter to `POST /webhooks` and `GET /webhooks`
* Added 5 new fields to the `Workspace` schema: `webhook_enabled`, `webhook_secret`, `webhook_secret_created_at`, `webhook_secret_rotated_at`, `ignore_company_webhooks`
* Added 2 new endpoints: `POST /workspaces/{id}/webhooks/rotate-secret`, `GET /workspaces/{id}/webhooks/secret-status`
* SSRF protection applied to webhook URL validation

### Migration Guide

**From v01.14.00 to v01.15.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* Company-level webhooks remain the default. The `workspace_id` parameter is optional on both create and list endpoints.
* Existing webhooks are unaffected. The new workspace fields on the workspace response default to `webhook_enabled: false` and `ignore_company_webhooks: false`.
* To adopt workspace webhooks, create a webhook with a `workspace_id`, then use the workspace secret rotation endpoint to generate a signing secret for that workspace.

***

## v01.14.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.14.00/openapi-v01.14.00.json)

### New Features

#### Recipient Designations

The `designation` field on signing request and template recipients now accepts three values: `"Signer"`, `"Approver"`, and `"CC"`.

* **Signer** — Signs the document (existing behavior, remains the default)
* **Approver** — Approves the document using approval-specific fields. Approvers do not sign but must complete all assigned approval fields before the request can finish.
* **CC** — Receives a completed copy of the signed document. CC recipients cannot sign or have fields assigned to them.

At least one Signer is still required per signing request.

#### Approval Field Types

Three new field types for Approver recipients:

* `approval_signature` — An approval stamp placed by the approver
* `approval_checkmark` — An approval checkbox
* `approval_date` — Auto-filled date when the approver approves

These field types can only be assigned to recipients with `"Approver"` designation.

#### CC Recipients

CC recipients are now supported across all create and update endpoints for both templates and signing requests. CC recipients appear in the recipient list but have no fields and do not participate in the signing or approval flow.

### Changes

* Expanded `designation` enum from `["Signer"]` to `["Signer", "Approver", "CC"]` across 7 schemas
* Added `approval_signature`, `approval_checkmark`, and `approval_date` to field type enums across 10 schemas

### Migration Guide

**From v01.13.00 to v01.14.00:**

This is a non-breaking additive change. Existing integrations continue to work without modification.

* New `designation` values are opt-in. Omitting the `designation` field defaults to `"Signer"`, preserving existing behavior.
* New field types are additive. All existing field type values remain valid and unchanged.
* If you integrate approval workflows, assign `"Approver"` designation to the relevant recipients and use the `approval_*` field types for their fields.

***

## v01.13.00

**Release Date:** April 12, 2026\
[Download OpenAPI Spec](/api-reference/v01.13.00/openapi-v01.13.00.json)

### New Features

#### Stamp Field Type

New `stamp` field type for placing pre-configured image stamps or company seals on documents. Stamps are read-only PNG images set by the template or signing request creator, rendered at signing time with no signer interaction, and embedded in the final PDF.

### Changes

* Added `stamp` to field type enums across all field-related schemas (templates, signing requests, create-and-send)
* Updated field type descriptions to document stamp behavior

### Migration Guide

**From v01.12.01 to v01.13.00:**

This is a non-breaking additive change. Existing integrations are not affected.

* If you create fields via the API, you can now use `"stamp"` as a field type. Stamp fields should be set as `read_only: true` with the stamp image as a PNG data URL in `read_only_value`.
* Stamp fields are also supported in anchor tags. When using anchor tags, the stamp image should be provided via `read_only_value` as a PNG data URL.

***

## v01.12.01

**Release Date:** April 2, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.01/openapi-v01.12.01.json)

### New Features

#### `variable_defined_name` on Field Responses

All API endpoints that return template or signing request fields now include a `variable_defined_name` property. This is the human-readable `field_name` from the custom field definition that the field is linked to.

Previously, fields linked to custom field definitions only exposed `variable_name`, which contains the internal identifier (e.g. `custom_template_a1b2c3d4-...`). The new `variable_defined_name` returns the name you originally defined (e.g. `artist_name`), making it straightforward to map fields in your integration without cross-referencing the custom fields endpoint.

**Affected endpoints:**

* `GET /templates` (list and single)
* `GET /templates/{id}/fields`
* `POST /templates/{id}/replace-document`
* `GET /signing-requests` (list)
* `GET /signing-requests/{id}/fields`
* `GET /documents` (legacy)

**Example response:**

```json theme={null}
{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}
```

For fields not linked to a custom field definition, `variable_defined_name` is `null`.

#### `variable_defined_name` as Input for Field Matching

When creating a signing request from a template via `POST /signing-requests/create-and-send`, you can now use `variable_defined_name` to target fields for overrides instead of the internal `variable_name`:

```json theme={null}
{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}
```

Both `variable_name` and `variable_defined_name` are accepted. `variable_name` takes precedence when both are provided.

### No Breaking Changes

This is a non-breaking patch release. All existing API behavior is unchanged.

***

## v01.12.00

**Release Date:** March 26, 2026\
[Download OpenAPI Spec](/api-reference/v01.12.00/openapi-v01.12.00.json)

### New Features

#### MCP Server Integration

Firma now supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), allowing AI assistants like Claude to interact with the Firma API through natural language. The MCP server exposes Firma's core API operations as tools that AI assistants can discover and call directly.

**Server URL:** `https://mcp.firma.dev/mcp`

**Authentication:**

* API key authentication via the `Authorization` header
* OAuth 2.1 with PKCE for browser-based clients (Claude.ai, Claude Desktop)

**Available tool categories:**

* Workspaces — list, create, get, update
* Templates — full CRUD, duplicate, view fields/users/reminders
* Signing Requests — full CRUD, send, cancel, resend, audit trails
* Webhooks — full CRUD, test delivery
* Company — view and update company information

**Transport:** [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — compatible with Claude Code, Claude Desktop, Claude.ai, and any MCP client supporting the standard.

See the [MCP Integration guide](/guides/mcp) for setup instructions and usage examples.

### No Breaking Changes

This release adds no new API endpoints or schema changes. The OpenAPI specification is unchanged from v1.11.0.

***

## v01.11.00

**Release Date:** March 19, 2026\
[Download OpenAPI Spec](/api-reference/v01.11.00/openapi-v01.11.00.json)

### New Features

#### File Upload Field Type

A new `file` field type allows signers to upload file attachments. Supported across signing requests and templates.

* Signers can upload images (JPG, PNG) and/or PDF files depending on configuration
* Files are validated by magic bytes, not just file extension
* Maximum file size: 10MB

**Configuration via `format_rules`:**

```json theme={null}
{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}
```

| `acceptedFileTypes` Value | Accepted Formats |
| - | - |
| `image_and_pdf` (default) | JPG, PNG, PDF |
| `image` | JPG, PNG only |
| `pdf` | PDF only |

#### Anchor Tags for Automatic Field Placement

A new `anchor_tags` array on signing request creation enables automatic field placement using text markers embedded in PDF documents (e.g., `{{SIGN_HERE}}`). The anchor text is removed from the PDF after processing by default.

* Up to 100 anchor tags per request
* Only available for document-based creation (not template-based)
* Fields created from anchor tags are added alongside any manually specified fields

**Key properties:**

| Property | Type | Default | Description |
| - | - | - | - |
| `anchor_string` | `string` (required) | — | Text to search for in the PDF |
| `type` | `string` (required) | — | Field type to place at anchor location |
| `recipient_id` | `string\|integer` (required) | — | Recipient assigned to the field |
| `x_offset` / `y_offset` | `number` | `0` | Offset from anchor position |
| `offset_units` | `percent` \| `pixels` | `percent` | Unit type for offsets |
| `width` / `height` | `number` | varies by type | Field dimensions as percentage of page |
| `occurrence` | `integer` | `0` (all) | Which occurrence to target (0 = all) |
| `ignore_if_not_present` | `boolean` | `false` | Skip without error if anchor not found |
| `remove_anchor_text` | `boolean` | `true` | Remove anchor text from PDF |
| `case_sensitive` | `boolean` | `false` | Case-sensitive matching |
| `match_whole_word` | `boolean` | `true` | Match whole words only |

**Example:**

```json theme={null}
{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}
```

#### Field Background Color

All field types now support a `background_color` property — a hex color string (e.g., `#FFFDE7`, `#fff`) useful for highlighting fields that need attention. Available on both standard fields and anchor tag definitions.

### Schema Changes

#### New Schemas

| Schema | Description |
| - | - |
| `FileFormatRules` | Formatting rules for file upload fields (`acceptedFileTypes` enum) |
| `AnchorTag` | Anchor tag definition for automatic field placement (\~25 properties) |

#### Field / TemplateField / SigningRequestField

| Added Field | Type | Description |
| - | - | - |
| `background_color` | `string \| null` | Hex color for field background (e.g., `#FFFDE7`) |

#### Field Type Enum

* Added `file` to the list of accepted field types

#### `format_rules`

* Now accepts `FileFormatRules` (with `acceptedFileTypes`) in addition to `DateFormatRules` and URL display text

#### Signing Request Creation

| Added Field | Type | Description |
| - | - | - |
| `anchor_tags` | `AnchorTag[]` | Anchor tags for automatic field placement (max 100) |

### Breaking Changes

#### `use_signing_order` Default Changed

The `use_signing_order` setting default has changed from `false` to `true`. This means new signing requests will enforce signing order by default. When `true`, signers receive the document in sequence based on their `order` field. Set `use_signing_order: false` explicitly to preserve the previous behavior where all signers receive the document simultaneously.

### Migration Guide

If you rely on the previous behavior where all signers receive documents simultaneously, explicitly set `use_signing_order: false` when creating signing requests. Review any integration code that creates signing requests without specifying this field.

***

## v01.10.00

**Release Date:** March 10, 2026\
[Download OpenAPI Spec](/api-reference/v01.10.00/openapi-v01.10.00.json)

### New Features

#### Conditional Field Logic

Fields now support conditional rules for both **required** status and **visibility**. Two new nullable properties are available on field objects:

* `required_conditions` — 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` — When set, the field is hidden unless the conditions evaluate to true. Hidden fields are not validated on submission.

Conditions use a nested group structure with logical operators:

| Schema | Description |
| - | - |
| `ConditionSet` | Top-level container with `logic` (`and`/`or`) operator and an array of `groups` |
| `ConditionGroup` | Contains an array of `conditions`, combined using the opposite of the parent's logic operator |
| `Condition` | Evaluates a single field by `field_id`, `operator`, and optional `value` |

**Supported operators:** `is_filled`, `is_empty`, `equals`, `not_equals`, `contains`, `not_contains`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`

**Example — Make a field required only when another field is filled:**

```json theme={null}
{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}
```

#### DOCX Document Support

All document upload endpoints now accept **DOCX files** in addition to PDF. DOCX files are automatically converted to PDF on upload. This applies to:

* Template creation (`POST /templates`)
* Template document replacement (`POST /templates/{id}/replace-document`)
* Signing request creation (`POST /signing-requests`)
* Template/signing request updates (PUT and PATCH)

#### Audit Trail Endpoint

A new endpoint retrieves 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.

**Endpoint:** `GET /signing-requests/{id}/audit`

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Audit event ID |
| `timestamp` | `date-time` | When the event occurred |
| `source` | `string` | `admin` or `signer` |
| `event` | `string` | Event type identifier |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action |
| `ip_address` | `string \| null` | IP address (signer events only) |
| `details` | `object \| null` | Additional event-specific metadata |

#### Signature Frame Control

A new `show_signature_frame` setting controls whether a visual frame with Signature ID is rendered around signatures in completed PDFs. Available at company, workspace, and signing request levels.

| Level | Field | Behavior |
| - | - | - |
| Company | `show_signature_frame` | Sets the default (enabled by default) |
| Workspace Settings | `show_signature_frame` | Overrides company default; `null` inherits |
| Signing Request Settings | `show_signature_frame` | Overrides workspace default; `null` inherits |

**Values:**

* `true` — Show signature frame with Signature ID
* `false` — Hide signature frame
* `null` — Inherit from parent level

#### Force Remove Conditions on User Deletion

When deleting recipients whose fields are referenced by conditions in other fields, a new `force_remove_conditions` boolean parameter controls behavior:

* `false` (default) — The request is rejected with an error listing the dependent fields
* `true` — Automatically removes the condition references and proceeds with deletion

This applies to both template and signing request user deletion operations.

### Schema Changes

#### Field

| Added Field | Type | Description |
| - | - | - |
| `required_conditions` | `ConditionSet \| null` | Conditional rules for when this field is required |
| `visibility_conditions` | `ConditionSet \| null` | Conditional rules for when this field is visible |

#### New Schemas

| Schema | Description |
| - | - |
| `ConditionSet` | A set of condition groups with nested logic (contains `logic` and `groups`) |
| `ConditionGroup` | A group of conditions (contains `conditions` array) |
| `Condition` | A single condition evaluating a field's value (contains `field_id`, `operator`, `value`) |

#### SigningRequestSettings / WorkspaceSettings / Company

| Added Field | Type | Description |
| - | - | - |
| `show_signature_frame` | `boolean \| null` | Whether to render signature frames in completed PDFs |

#### Template & Signing Request User Deletion

| Added Parameter | Type | Description |
| - | - | - |
| `force_remove_conditions` | `boolean` | Force-remove condition references when deleting users whose fields are referenced (default: `false`) |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/signing-requests/{id}/audit` | GET | Get signing request audit trail |

### Migration Guide

No breaking changes. All new features are additive:

* Conditional field properties default to `null` (no conditions)
* `show_signature_frame` defaults to `null` (inherit, which is enabled by default)
* `force_remove_conditions` defaults to `false` (preserving existing rejection behavior)
* DOCX support is transparent — existing PDF uploads continue to work unchanged
* The audit trail endpoint is purely additive

***

## v01.09.00

**Release Date:** March 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.09.00/openapi-v01.09.00.json)

### New Features

#### OTP Email Verification

A new `require_otp_verification` setting allows you to require signers to verify their email address with a one-time code before accessing signing documents. This adds an extra layer of identity verification.

**Where it's available:**

| Level | Field | Behavior |
| - | - | - |
| Company | `require_otp_verification` | Sets the default for all workspaces |
| Workspace Settings | `require_otp_verification` | Overrides company default; `null` inherits from company |
| Signing Request Settings | `require_otp_verification` | Overrides workspace default; `null` inherits from workspace |

**Values:**

* `true` — Require OTP verification before document access
* `false` — Do not require OTP verification
* `null` — Inherit from parent level (workspace → company, signing request → workspace)

**Example — Enable OTP at workspace level:**

```json theme={null}
PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}
```

This route was part of the historical release note. The current endpoint is `PUT /workspace/{workspace_id}/settings`.

**Example — Override for a specific signing request:**

```json theme={null}
PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}
```

#### Replace Template Document

A new endpoint allows replacing a template's PDF document while preserving all field placements. This is useful when you need to update a document (e.g., fixing a typo) without recreating all the field configurations.

**Endpoint:** `POST /templates/{id}/replace-document`

**Requirements:**

* The replacement document must have the **same page count** as the original
* Page dimensions must match within **1pt tolerance**
* Document must be provided as a **base64-encoded PDF**

**Example:**

```json theme={null}
POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}
```

**Error cases:**

| Error | Cause |
| - | - |
| 400 | Page count mismatch |
| 400 | Page dimension mismatch (exceeds 1pt tolerance) |
| 400 | Invalid or corrupt PDF document |

### Schema Changes

#### SigningRequestSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from workspace |

#### WorkspaceSettings

| Added Field | Type | Description |
| - | - | - |
| `require_otp_verification` | `boolean \| null` | Require OTP email verification; `null` inherits from company |

### New Endpoints

| Endpoint | Method | Description |
| - | - | - |
| `/templates/{id}/replace-document` | POST | Replace template PDF while preserving fields |

### Migration Guide

No breaking changes. The `require_otp_verification` field defaults to `null` (inherit), so existing behavior is unchanged. The replace document endpoint is purely additive.

***

## v01.08.00

**Release Date:** March 3, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.08.00/openapi-v01.08.00.json)

### New Features

#### Email Templates API

A new **Email Templates** endpoint group allows you to customize the notification emails sent during the signing process. Templates can be configured at both company and workspace levels, with workspace-level templates overriding company-level defaults.

**Supported email types:**

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines |

**New endpoints:**

| Endpoint | Description |
| - | - |
| `GET /workspace/{workspace_id}/email-templates` | List workspace email templates |
| `GET /workspace/{workspace_id}/email-templates/{email_type}` | Get a specific workspace email template |
| `PUT /workspace/{workspace_id}/email-templates/{email_type}` | Create or update a workspace email template |
| `DELETE /workspace/{workspace_id}/email-templates/{email_type}` | Delete a workspace email template |
| `GET /company/email-templates` | List company email templates |
| `PUT /company/email-templates/{email_type}` | Create or update a company email template |
| `DELETE /company/email-templates/{email_type}` | Delete a company email template |
| `GET /email-templates/defaults/{language}` | Get built-in default templates for a language |
| `GET /email-templates/placeholders` | Get available template placeholders |

**Template hierarchy:** Workspace templates → Company templates → Built-in defaults.

Templates support HTML bodies with placeholders like `{{signing_link}}`, `{{signer_name}}`, etc. A warning is returned if the body does not contain `{{signing_link}}`.

**Example:**

```json theme={null}
PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}
```

#### Language Support

New `language` field added to both the `Company` and `WorkspaceSettings` schemas to support multi-language email templates.

| Field | Type | Values | Default |
| - | - | - | - |
| `language` | `string` | `en`, `es`, `it`, `pt`, `fr`, `de`, `el` | `en` |

### Schema Changes

#### Timestamp Corrections

Timestamp field names have been corrected in the spec to match actual API responses:

| Schema | Previous Spec | Corrected |
| - | - | - |
| `Company` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Workspace` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Template` | `date_created`, `date_changed` | `created_date`, `updated_date` |
| `Reminder` | `date_created`, `date_changed` | `created_at`, `updated_at` |
| `Webhook` | `date_created`, `date_changed` | `created_at`, `updated_at` |

> [!NOTE]
>
> These are spec corrections only — the API responses have not changed. If your integration already handles the actual API response fields, no code changes are needed.

#### Company Schema

| Change | Details |
| - | - |
| Corrected | `company_name` → `name` (matches actual API response) |
| Added | `language` (enum, default `"en"`) |
| Corrected | `date_created`/`date_changed` → `created_date`/`updated_date` |

#### Template Schema (Expanded)

The `Template` schema now includes inline recipients and fields when fetching a single template (`GET /templates/{id}`), reducing the need for separate API calls.

| Added Field | Type | Description |
| - | - | - |
| `page_count` | `integer` | Number of pages in the document |
| `expiration_hours` | `integer` | Hours until signing requests expire (default: 168) |
| `settings` | `SigningRequestSettings` | Template-level settings |
| `recipients` | `array` | Template recipients (inline) |
| `fields` | `array` | Template fields (inline) |

#### Signing Request Response Shapes

The monolithic `SigningRequest` schema has been split into endpoint-specific response shapes:

| Schema | Used By |
| - | - |
| `SigningRequestListItem` | `GET /signing-requests` (list) |
| `SigningRequestCreateResponse` | `POST /signing-requests`, `POST /documents` |
| `SigningRequestDetail` | `GET /signing-requests/{id}` (unchanged from v1.7.0) |

The list and create responses now include inline `recipients` and `fields` arrays, and use standardized timestamp fields (`created_date`, `sent_date`, `finished_date`, etc.).

#### SigningRequestSettings

`use_signing_order` (boolean, default `false`) is now included in the settings object. Previously this was only available as a deprecated top-level integer field.

#### Reminder Schema

| Added Field | Description |
| - | - |
| `recipient_id` | Specific recipient to send reminder to (signing request context) |
| `sent_on` | Timestamp when the reminder was actually sent |

#### Webhook Schema

| Added Field | Type | Description |
| - | - | - |
| `description` | `string` | Webhook description |
| `consecutive_failures` | `integer` | Number of consecutive delivery failures |
| `auto_disabled_at` | `datetime` | When the webhook was auto-disabled due to failures |

#### SendSigningRequestResponse (Corrected)

The spec now accurately reflects the actual response shape:

| Previous Spec | Corrected |
| - | - |
| `success` (boolean) | `message` (string) |
| `sentTo` (email) | `signing_request_id` (uuid) |
| `sentAt` (datetime) | `recipients_notified` (integer), `sent_date`, `expires_at` |

#### WorkspaceSettings

| Added Field | Description |
| - | - |
| `name` | Workspace name |
| `language` | Workspace language for email templates |

***

## v01.07.00

**Release Date:** February 25, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.07.00/openapi-v01.07.00.json)

### New Features

#### Hand-Drawn Only Signatures

A new `hand_drawn_only` setting allows you to require signers to hand-draw their signatures instead of using typed or font-based options.

**Added to `SigningRequestSettings` schema:**

| Field | Type | Default | Description |
| - | - | - | - |
| `hand_drawn_only` | `boolean` | `false` | When enabled, signers can only hand-draw their signatures |

This setting is available in all places where signing request settings are configured:

* Creating signing requests (`POST /signing-requests`)
* Creating and sending signing requests (`POST /signing-requests/create-and-send`)
* Comprehensive updates (`PUT /signing-requests/{id}`)
* Partial updates (`PATCH /signing-requests/{id}`)
* Template creation and updates

**Example:**

```json theme={null}
{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}
```

### Schema Changes

#### Deprecated Legacy Settings Fields

The `SigningRequest` schema now includes deprecated top-level integer fields that mirror the boolean `settings` object. These exist for backward compatibility and should not be used in new integrations:

| Deprecated Field | Type | Use Instead |
| - | - | - |
| `use_signing_order` | `integer` (0/1) | `settings.use_signing_order` |
| `allow_download` | `integer` (0/1) | `settings.allow_download` |
| `allow_editing_before_sending` | `integer` (0/1) | `settings.allow_editing_before_sending` |
| `hand_drawn_only` | `integer` (0/1) | `settings.hand_drawn_only` |
| `attach_pdf_on_finish` | `integer` (0/1) | `settings.attach_pdf_on_finish` |

> [!WARNING]
>
> These deprecated fields use `0`/`1` integers instead of booleans. Always use the `settings` object for new integrations.

### Migration Guide

No breaking changes. The `hand_drawn_only` setting defaults to `false`, preserving existing behavior. Deprecated top-level integer fields are purely additive.

***

## v01.06.00

**Release Date:** February 12, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.06.00/openapi-v01.06.00.json)

### New Features

#### Split PDF Downloads

Completed signing requests now support downloading the signed document and audit trail certificate as separate files, in addition to the existing combined download.

**New fields on `SigningRequest` schema:**

| Field | Description |
| - | - |
| `document_only_download_url` | Signed URL to download just the signed document (without certificate/audit trail pages) |
| `document_only_download_error` | Error indicator if the document-only file is inaccessible |
| `certificate_only_download_url` | Signed URL to download just the certificate/audit trail pages |
| `certificate_only_download_error` | Error indicator if the certificate-only file is inaccessible |

**Notes:**

* Only available when the split PDF feature has been applied to the signing request
* URLs expire after 1 hour — fetch the signing request again for a fresh URL
* Error fields return `"file_not_accessible"` if the file path exists but the file is missing

**Example Response (partial):**

```json theme={null}
{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}
```

### Schema Changes

#### Field Type Normalization

Field type enums now accept both original and normalized forms across all schemas. The API normalizes inputs automatically:

| Input | Normalized To |
| - | - |
| `initials` | `initial` |
| `textarea` | `text_area` |

**Affected schemas:**

| Schema | Change |
| - | - |
| `TemplateField.type` | `initials` → `initial`; enum now includes both `initial` and `initials` variants |
| `Field.type` (signing requests) | Now accepts `initial`/`initials` and `textarea`/`text_area` |
| `SigningRequestField.field_type` | `initials` → `initial`, `textarea` → `text_area` |
| Template PATCH `field.type` | Now accepts both forms with normalization |
| Signing Request PATCH `field.type` | Now accepts both forms with normalization |

### Migration Guide

No breaking changes. Both old and new field type names are accepted. The split PDF download fields are purely additive.

***

## v01.05.00

**Release Date:** February 5, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.05.00/openapi-v01.05.00.json)

### New Features

#### Email Validation Warnings

Signing request endpoints now return non-blocking warnings when recipient email addresses have potentially invalid formats (e.g., unusual TLDs, missing dots). These warnings help identify potential delivery issues without failing the request.

**Affected Endpoints:**

| Endpoint | Response Field |
| - | - |
| `POST /signing-requests` (create) | `warnings` array |
| `PATCH /signing-requests/{id}` (partial update) | `warning` field |
| `PUT /signing-requests/{id}` (comprehensive update) | `warnings` array |

**Example Response:**

```json theme={null}
{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}
```

**Notes:**

* Warnings are non-blocking — the request still succeeds
* Useful for flagging potential typos or invalid email domains
* Check the `warnings` or `warning` field in the response to surface these to users

### Migration Guide

No breaking changes. Email validation warnings are purely additive and do not affect existing integrations.

***

## v01.04.00

**Release Date:** January 31, 2026\
[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.04.00/openapi-v01.04.00.json)

### New Features

#### New Field Types

Three new field types have been added:

| Field Type | Description |
| - | - |
| `textarea` | Multi-line text input field |
| `url` | Clickable link field (automatically read-only) |
| `radio_buttons` | Radio button group (renamed from `radio`) |

**URL Field Details:**

* Automatically set to `read_only: true`
* Use `read_only_value` to set the target URL
* Use `format_rules.urlDisplayText` to customize the display text

Example:

```json theme={null}
{
  "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" }
  }
}
```

#### PATCH Field Operations

Both Template and Signing Request PATCH endpoints now support single-field operations:

**Template PATCH** (`PATCH /templates/{id}`):

* Can now update properties, a single user, **OR a single field**
* Include `field` object in request body
* Include `field.id` to update existing field, omit to create new

**Signing Request PATCH** (`PATCH /signing-requests/{id}`):

* Can now update properties, a single recipient, **OR a single field**
* Same field object structure as templates

Example - Create new field:

```json theme={null}
{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}
```

Example - Update existing field:

```json theme={null}
{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}
```

#### Template User Matching for Recipients

When creating signing requests from templates, you can now use `template_user_id` to explicitly match recipients to template users:

```json theme={null}
{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}
```

* `template_user_id` is the preferred method for matching
* `order` remains available as a fallback

### Schema Changes

#### Field Type Enum

Updated from:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]
```

To:

```
["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]
```

#### Recipient Schema

* Signing request creation now uses shared `Recipient` schema reference
* Added `template_user_id` property for explicit template user matching

***

## v01.03.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.03.00/openapi-v01.03.00.json)

### New Features

#### Email Domains API

A complete new API category for configuring custom email domains for sending signing request emails:

**New Endpoints:**

* `GET /company/domains` - List all company email domains
* `POST /company/domains` - Add a new email domain
* `GET /company/domains/{id}` - Get domain details
* `DELETE /company/domains/{id}` - Delete a domain
* `POST /company/domains/{id}/verify-ownership` - Verify domain ownership via TXT record
* `POST /company/domains/{id}/finalize` - Complete domain setup with email provider
* `POST /company/domains/{id}/verify-dns` - Verify SPF, DKIM, DMARC records
* `POST /company/domains/{id}/set-primary` - Set primary sending domain

**New Schemas:**

* `Domain` - Email domain configuration with verification status
* `DomainDnsRecord` - DNS record details for domain verification

#### Credit Cost Tracking

* Added `credit_cost` field to `Template` schema - Number of credits consumed when sending
* Added `credit_cost` field to `SigningRequest` schema - Credits consumed when sent

#### Signing Request Declined Status

* Added `declined` to `SigningRequest.status` enum values
* Added `date_declined` field to `SigningRequest` schema

### Schema Improvements

#### Template Fields

* Added `date_default` field for setting default date values (ISO 8601 format)
* Enhanced `multi_group_id` description: explains mutually exclusive field grouping for checkboxes/radio buttons
* Added clarification that `page_number` is 1-indexed and must not exceed document page count

#### Signing Request Fields

* Enhanced `multi_group_id` description with same improvements as template fields

***

## v01.02.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.02.00/openapi-v01.02.00.json)

### Enhanced User Information

#### TemplateUser Schema Enhancements

Added comprehensive recipient information fields:

* `first_name` - Recipient first name
* `last_name` - Recipient last name
* `phone_number` - Contact phone number
* `street_address` - Street address
* `city` - City
* `state_province` - State or province
* `postal_code` - Postal/ZIP code
* `country` - Country
* `title` - Job title
* `company` - Company name

#### Ready-to-Send Indicators

New fields to help determine recipient readiness:

* `required_fields` - List of required recipient data fields based on template configuration
* `missing_fields` - List of required fields that are currently empty
* `required_read_only_fields` - Read-only fields needing pre-filled values
* `ready_to_send` - Boolean indicating if recipient has all required data

#### SigningRequestUser Schema Enhancements

Same enhancements as TemplateUser, plus:

* `declined_on` - Timestamp when recipient declined to sign
* `decline_reason` - Reason provided by recipient for declining
* `custom_fields` - Custom field values for the recipient
* `has_value` property in `required_read_only_fields` - Indicates if read-only field has a value

### Response Format Changes

Template users endpoint (`GET /templates/{id}/users`) now returns:

```json theme={null}
{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}
```

***

## v01.01.00

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.01.00/openapi-v01.01.00.json)

### New Endpoints

#### Template Management

Full CRUD support for templates:

* `POST /templates` - Create a new template with base64-encoded PDF
* `PATCH /templates/{id}` - Partial update (properties OR single user)
* `PUT /templates/{id}` - Comprehensive update (properties, users, fields, reminders)
* `DELETE /templates/{id}` - Soft delete a template

#### Template Sub-Resources

* `GET /templates/{id}/users` - Get all template recipients
* `GET /templates/{id}/fields` - Get all template fields
* `GET /templates/{id}/reminders` - Get all template reminders

#### API Key Management

New endpoints for workspace API key lifecycle:

* `POST /workspaces/{id}/api-key/regenerate` - Generate new API key with 24-hour grace period
* `POST /workspaces/{id}/api-key/expire` - Immediately expire pending keys

### Enhanced Operations

#### Comprehensive Updates

The PUT endpoint for templates supports:

* `template_properties` - Update metadata and settings
* `users` - Upsert users (include id to update, omit to create)
* `deleted_users` - Delete users with field handling strategy (`delete` or `reassign`)
* `fields` - Upsert fields
* `reminders` - Upsert reminders

Example request:

```json theme={null}
{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}
```

***

## v01.00.02

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.02/openapi-v01.00.02.json)

### New Features

#### Custom Fields API

Added custom field definition management for workspaces, templates, and signing requests.

**New Tag:**

* `Custom Fields` - Custom field definition management

**New Schemas:**

##### WorkspaceCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### TemplateCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

##### SigningRequestCustomField

```json theme={null}
{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Schema Improvements

#### TemplateField Schema

Enhanced with clearer descriptions and additional properties:

* Explicit `type` property with enum values
* `position` object with x, y, width, height
* `read_only` and `read_only_value` for pre-filled fields

***

## v01.00.01

[Download OpenAPI Spec](https://github.com/Firma-esign/firma-docs/raw/4b2cbdb9cd36b46fcbd1cf06f8e079533487c45d/api-reference/v01.00.01/openapi-v01.00.01.json)

### Initial Release

The initial release of the Firma Partner API with the following core features:

#### API Tags / Categories

* **Company** - Company information and settings
* **Workspaces** - Workspace management operations
* **Templates** - Template management operations
* **Signing Requests** - Document signing request operations
* **Webhooks** - Webhook configuration and management
* **JWT Management** - JWT token generation and revocation
* **Legacy** - Deprecated endpoints for backward compatibility

#### Authentication

* API key authentication via `Authorization` header
* Optional Bearer prefix support

#### Rate Limiting

Tiered rate limits based on operation type:

* Read operations (GET): 200 requests/minute
* Write operations (POST/PUT/PATCH/DELETE): 120 requests/minute
* Webhook CRUD: 60 requests/minute
* Webhook test: 10 requests/minute
* API key operations: 1 request/minute
* Secret rotation: 1 request/minute

#### Core Schemas

##### Company

* `id`, `company_name`, `account_owner`, `account_owner_email`
* `website`, `icon_url`, `credits` (read-only)
* `date_created`, `date_changed`

##### Workspace

* `id`, `name`, `protected`, `api_key`
* `date_created`, `date_changed`

##### Template

* `id`, `name`, `description`
* `document_url` (pre-signed, expires)
* `document_url_expires_at`
* `date_created`, `date_changed`

##### SigningRequest

* `id`, `name`, `description`
* `document_url`, `document_url_expires_at`
* `document_page_count`, `status`, `expiration_hours`
* `settings`, `template_id`
* Date fields: `date_created`, `date_sent`, `date_finished`, `date_cancelled`, `expires_at`
* `certificate` object with generation status
* `final_document_download_url`, `final_document_download_error`

##### Recipient

* Core: `id`, `first_name`, `last_name`, `email`, `designation`, `order`
* Address: `street_address`, `city`, `state_province`, `postal_code`, `country`
* Professional: `phone_number`, `title`, `company`
* `custom_fields` for additional data
* Temporary ID support for document-based creation

##### Field

* `id`, `type`, `position`, `page_number`, `required`
* `recipient_id`, `variable_name`
* Type-specific: `dropdown_options`, `date_default`, `date_signing_default`
* Read-only: `read_only`, `read_only_value`, `prefilled_data`
* Formatting: `format_rules`, `validation_rules`

##### Webhook

* `id`, `url`, `events`, `enabled`
* `date_created`, `date_changed`

#### JWT Management

* Generate JWT for template embedding
* Generate JWT for signing request embedding
* Revoke JWT tokens

***

## Migration Guide

### Migrating from v01.00.01 to v01.00.02

* No breaking changes
* Custom Fields API available for use

### Migrating from v01.00.02 to v01.01.00

* No breaking changes
* New template management endpoints available
* API key regeneration endpoints available

### Migrating from v01.01.00 to v01.02.00

* No breaking changes
* Template and signing request users now include additional fields
* `ready_to_send` boolean available to check recipient readiness

### Migrating from v01.02.00 to v01.03.00

* No breaking changes
* Email domain configuration available for custom sending domains
* `declined` status added to signing request status enum
* Credit cost tracking available on templates and signing requests

### Migrating from v01.03.00 to v01.04.00

* No breaking changes
* `radio` field type renamed to `radio_buttons` (both still accepted)
* New field types available: `textarea`, `url`
* PATCH endpoints now support single-field operations
* Use `template_user_id` for explicit template user matching in signing requests

### Migrating from v01.04.00 to v01.05.00

* No breaking changes
* Email validation warnings are purely additive

### Migrating from v01.05.00 to v01.06.00

* No breaking changes
* Split PDF download URLs available on completed signing requests
* Field type inputs `initials`/`initial` and `textarea`/`text_area` both accepted with automatic normalization

### Migrating from v01.06.00 to v01.07.00

* No breaking changes
* New `hand_drawn_only` setting available in signing request settings (defaults to `false`)
* Deprecated top-level integer settings fields now visible in `SigningRequest` schema — use `settings` object instead

### Migrating from v01.07.00 to v01.08.00

* No breaking changes — schema field name corrections reflect actual API responses
* New Email Templates API for customizing signing notification emails
* `language` field added to `Company` and `WorkspaceSettings`
* Template schema expanded with inline `recipients`, `fields`, `settings`, `page_count`, `expiration_hours`
* `use_signing_order` added to `SigningRequestSettings`
* Webhook schema includes `description`, `consecutive_failures`, `auto_disabled_at`
* Signing request responses split into endpoint-specific shapes with inline data

### Migrating from v01.08.00 to v01.09.00

* No breaking changes
* New `require_otp_verification` setting available at company, workspace, and signing request levels
* New `POST /templates/{id}/replace-document` endpoint for replacing template PDFs while preserving fields

### Migrating from v01.09.00 to v01.10.00

* No breaking changes
* Conditional field logic available via `required_conditions` and `visibility_conditions` on fields
* DOCX files now accepted alongside PDF in all document upload endpoints
* New `GET /signing-requests/{id}/audit` endpoint for retrieving audit trails
* New `show_signature_frame` setting at company, workspace, and signing request levels
* New `force_remove_conditions` parameter on user deletion operations

### Migrating from v01.10.00 to v01.11.00

* **Breaking change:** `use_signing_order` default changed from `false` to `true` — explicitly set `use_signing_order: false` if you rely on simultaneous delivery
* New `file` field type for signer file uploads
* Anchor tags for automatic field placement from text markers in PDFs
* `background_color` property available on all field types

### Migrating from v01.11.00 to v01.12.00

* No breaking changes
* MCP Server integration for AI assistant access to the Firma API
* No new API endpoints or schema changes — OpenAPI specification unchanged from v1.11.0

### Migrating from v01.12.00 to v01.12.01

* No breaking changes
* New `variable_defined_name` field on all field responses — returns the human-readable custom field definition name alongside the internal `variable_name`
* `variable_defined_name` accepted as input for field matching on `POST /signing-requests/create-and-send`

### Migrating from v01.15.03 to v01.16.00

* No breaking changes
* New `GET /signing-requests/{id}/download` endpoint for retrieving a download URL for the signed document
* Partial downloads available when `allow_partial_download` is enabled in signing request settings

### Migrating from v01.16.00 to v01.17.00

* No breaking changes
* Six new nullable color fields (`color_primary`, `color_primary_fg`, `color_background`, `color_foreground`, `color_card`, `color_border`) on Company and Workspace Settings
* New `ColorPalette` schema for resolved signing experience colors
* Colors follow a 3-tier cascade: Firma defaults -> Company -> Workspace

### Migrating from v1.19.0 to v1.20.0

* No breaking changes
* New `disable_guided_navigation` setting available at company, workspace, template, and signing request levels
* Follows the same cascading pattern as `require_otp_verification`: signing request -> workspace -> company (first non-null wins)
* Defaults to `false` (auto-scroll enabled), preserving existing behavior

### Migrating from v1.20.0 to v1.21.0

* No breaking changes
* New `email_local_part` setting on Company (`GET/PATCH /company`) and Workspace Settings (`GET/PUT /workspace/{id}/settings`)
* Workspace value takes priority over company value; default is `"support"`
* Only applies when a verified custom domain is configured

### Migrating from v1.38.0 to v1.39.0

* No breaking changes
* At launch, before October 13, 2026, multi-document features required enablement for your company; companies that were not enabled saw no change
* New `document_ids` on `POST /templates`, `POST /signing-requests`, and `POST /signing-requests/create-and-send`, and new `/documents` routes on templates and signing requests
* On enabled companies, `anchor_tags[].document_index` selects the document an anchor tag is searched in on multi-document requests
* Send `documents_layout_version` with field writes on templates and signing requests that have more than one document

### Migrating from v1.40.0 to v1.40.1

* No change for valid PDFs
* A PDF with a page that has no valid content returns `400 MALFORMED_PDF` with `malformed_pages`; nothing is written
* An unreadable PDF, including an encrypted one, returns `400 VALIDATION_ERROR` instead of `500`

### Migrating from v1.40.1 to v1.40.2

* No API change
* The `events` list of `POST /webhooks` and `PUT /webhooks/{id}` now names the 26 events Firma.dev sends; regenerate clients built from the spec


# API Versioning
Source: https://docs.firma.dev/guides/api-versioning

Learn how the Firma API handles versioning, deprecation, and breaking changes

# API Versioning Guide

The Firma API uses header-based versioning via the `X-API-Version` header. This allows you to specify which API version you want to use, with automatic deprecation warnings and a structured sunset process.

## How to Specify a Version

Include the `X-API-Version` header in your request:

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
```

> [!NOTE]
>
> If the `X-API-Version` header is omitted, the API defaults to the current stable version (currently **1**).

## Version Lifecycle

Each API version goes through three stages:

| Status | Description | Behavior |
| - | - | - |
| **active** | Fully supported version | Normal responses with `X-API-Version` header |
| **deprecated** | Still functional but scheduled for removal | Responses include deprecation warning headers |
| **sunset** | Removed from service | Returns `410 Gone` error |

## Response Headers

### For Active Versions

```
X-API-Version: 1
```

### For Deprecated Versions

When a version is deprecated, the following headers are included in every response:

```
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
```

| Header | Description |
| - | - |
| `Deprecation` | RFC 8594 compliant - Date when the version was deprecated |
| `Sunset` | RFC 8594 compliant - Date when the version will be removed |
| `X-Deprecated-Message` | Human-readable warning message |

## Error Responses

### Invalid Version Header

```json theme={null}
// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}
```

### Unsupported Version

```json theme={null}
// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}
```

### Sunset Version (Removed)

```json theme={null}
// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}
```

## Breaking Changes Policy

> [!NOTE]
>
> Breaking changes are only introduced in major version increments (e.g., v1 → v2). Non-breaking changes such as new optional fields or new endpoints do not require a new version.

When a new major version is released:

1. **The previous version is marked as deprecated**
2. **You'll receive warning headers** for a recommended 6-month deprecation period
3. **After the sunset date**, the old version returns `410 Gone`

### What Constitutes a Breaking Change?

Breaking changes include:

* Removing or renaming existing fields
* Changing field types or validation rules
* Removing endpoints
* Changing authentication requirements
* Modifying rate limits significantly

Non-breaking changes include:

* Adding new optional fields
* Adding new endpoints
* Adding new enum values (if your client handles unknown values gracefully)
* Improving error messages

## Best Practices

> **Always check for deprecation headers**
>
> Implement automated checks in your API client code to detect `Deprecation` and `Sunset` headers. Log warnings when these headers are present.
>
> ```javascript theme={null}
> const response = await fetch(url, options);
>
> if (response.headers.get('Deprecation')) {
>   console.warn('API Deprecation Warning:', {
>     deprecation: response.headers.get('Deprecation'),
>     sunset: response.headers.get('Sunset'),
>     message: response.headers.get('X-Deprecated-Message')
>   });
> }
> ```

> **Explicitly specify the version**
>
> Rather than relying on the default version, always specify the `X-API-Version` header explicitly. This prevents unexpected breaking changes when the default version changes.
>
> ```javascript theme={null}
> // Good - explicit version
> headers: { 'X-API-Version': '1' }
>
> // Avoid - relies on default
> headers: { }
> ```

> **Subscribe to changelog updates**
>
> Stay informed about upcoming changes by subscribing to the changelog or API announcements. This gives you advance notice of:
>
> * New version releases
> * Deprecation schedules
> * Breaking changes
> * Migration guides

> **Test against new versions early**
>
> When a new version is announced, test your integration against it well before the sunset date of the old version. This gives you time to:
>
> * Identify breaking changes in your implementation
> * Update your code and dependencies
> * Test thoroughly in staging
> * Deploy with confidence before the deadline

## Current Version Status

The current active version is **v1** with no deprecation scheduled at this time.

> [!NOTE]
>
> When new versions are released or deprecation schedules are announced, this guide will be updated with specific dates and migration information.

## Related Resources

> **[Authentication](/guides/authentication)**
>
> Learn about API key authentication and JWT tokens

> **[Complete Setup Guide](/guides/complete-setup-guide)**
>
> Get started with the Firma API

> **[Webhooks](/guides/webhooks)**
>
> Set up webhook notifications for events

> **[API Reference](/api-reference/v01.15.00/company/get-company-information)**
>
> Browse all API endpoints


# Audit Trail
Source: https://docs.firma.dev/guides/audit-trail

Track every action on a signing request for compliance and reporting.

Every signing request in Firma has a complete audit trail. Every document view, field interaction, signature, decline, and admin action is recorded with timestamps, actor identity, and IP addresses.

The finalized PDF and its completion certificate include `Signing Request ID: <id>` near the top of every page. This identifier cannot be removed with a workspace or API setting.

Common use cases:

* **Compliance and legal evidence** — prove who signed what, when, and from where
* **Debugging signer issues** — see exactly what a recipient did during their signing session
* **Internal reporting** — track admin actions like creation, edits, and cancellations

The audit trail captures two categories of events:

* **Signer events** — document views, field interactions, signing, declining, certificate downloads
* **Admin events** — creation, edits, sending, cancellation, resending (via dashboard or API)

Each event includes a timestamp, a human-readable description, actor identity, and (for signer events) the signer's IP address.

## Viewing the audit trail in the dashboard

Open any signing request in the Firma dashboard and click the **Audit Trail** tab. You'll see a chronological timeline of all events, with signer actions and admin actions visually distinguished. Consecutive repetitive events (like scrolling or repeated field interactions) are automatically condensed with a count indicator.

### Authentication on the completion certificate

Every signer row on the completion certificate carries an `Authentication:` line that reads `Email Link` or `Email Link + One-Time Code`. For a code signer, the line ends with `(code verified <time>)`, the time the signer entered the code. The Identity row at the top of the certificate shows the shared method, or `Mixed (see signers)` when the signers differ. The code time can precede the `Viewed` time printed above it, because the signer enters the code before the document loads.

## Retrieving the audit trail via API

Use the audit endpoint to fetch the full event history for a signing request:

```
GET /signing-requests/{id}/audit
```

### curl

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit" \
  -H "Authorization: YOUR_API_KEY"
```

### Node.js

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/audit`,
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
    },
  }
);

const { results } = await response.json();
console.log(results);
```

### Python

```python theme={null}
import os
import requests

response = requests.get(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}/audit",
    headers={
        "Authorization": os.environ["FIRMA_API_KEY"],
    },
)

results = response.json()["results"]
```

### Example response

```json theme={null}
{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "timestamp": "2025-01-15T10:00:00.000Z",
      "source": "admin",
      "event": "activity",
      "description": "Created signing request via API",
      "actor": { "type": "api_key" },
      "ip_address": null,
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "timestamp": "2025-01-15T10:05:12.000Z",
      "source": "signer",
      "event": "document_viewed",
      "description": "Viewed the document",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "timestamp": "2025-01-15T10:06:30.000Z",
      "source": "signer",
      "event": "field_interaction",
      "description": "Completed signature field",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": {
        "field_type": "signature",
        "action": "field_completed",
        "interaction_count": 1
      }
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "timestamp": "2025-01-15T10:06:45.000Z",
      "source": "signer",
      "event": "page_viewed",
      "description": "Viewed page 2 (×3)",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": { "page_number": 2 },
      "condensed_count": 3
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "timestamp": "2025-01-15T10:07:00.000Z",
      "source": "signer",
      "event": "document_finished",
      "description": "Completed signing",
      "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
      "ip_address": "203.0.113.42",
      "details": null
    }
  ]
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | `uuid` | Event ID |
| `timestamp` | `datetime` | When the event occurred |
| `source` | `string` | `"signer"` or `"admin"` |
| `event` | `string` | Event type identifier (see [event reference](#event-reference) below) |
| `description` | `string` | Human-readable event description |
| `actor` | `object \| null` | Who performed the action (see below) |
| `ip_address` | `string \| null` | Signer's IP address (signer events only) |
| `details` | `object \| null` | Event-specific metadata |
| `condensed_count` | `integer` | Present when consecutive identical events from the same actor are grouped |

## Understanding event sources

The `source` field tells you whether an event came from a signer or an admin, and the `actor` field has a different shape for each.

### Signer events

Events with `source: "signer"` are actions taken by recipients during the signing flow. The `actor` object contains the signer's `name` and `email`. The `ip_address` field is populated.

```json theme={null}
{
  "source": "signer",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42"
}
```

Organization seal events (`organization_seal_*`) use `source: "signer"` with `actor` and `ip_address` set to `null`. Firma.dev records them when it applies, pauses, swaps, or repins a seal, and `details` holds the seal's data.

### Admin events

Events with `source: "admin"` are actions taken via the dashboard or API. The `actor` object contains a `type` field (`"api_key"` or `"user"`) and optionally a `user_id`. The `ip_address` field is `null`.

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "api_key" },
  "ip_address": null
}
```

```json theme={null}
{
  "source": "admin",
  "actor": { "type": "user", "user_id": "usr_abc123" },
  "ip_address": null
}
```

Three admin actions write these descriptions:

* Cancel from the dashboard: `Signing Request Cancellation requested`
* Delete from the dashboard: `Signing Request Deletion requested`
* Certificate retry: `Certificate regeneration requested`

Firma.dev writes each line before the change, so the line stays when the action then fails or loses a race. "Requested" records the request; it does not confirm completion. Rows written before [API v1.40.3](/guides/api-changelog#v1-40-3) keep the old wording (`Signing Request Cancelled` / `Signing Request Deleted`).

## Real-time tracking via webhooks

If you need real-time notification of signer events rather than polling the audit endpoint, Firma supports webhooks. See the [Webhooks guide](/guides/webhooks) for setup instructions.

## Event reference

### Document lifecycle

| Event | Description | Has `details` |
| - | - | - |
| `document_opened` | Opened the document | No |
| `document_viewed` | Viewed the document | No |
| `document_saved` | Saved field values | No |
| `document_finished` | Completed signing | Yes: `otp_code_id` (code signers only) |
| `document_signed` | Signed the document | No |
| `document_hidden` | Left the page | No |
| `document_visible` | Returned to the page | No |
| `document_closed` | Closed the document | No |

### Signature and verification

| Event | Description | Has `details` |
| - | - | - |
| `signature_finalized` | Signature finalized | No |
| `signing_declined` | Declined to sign | No |
| `terms_accepted` | Accepted terms and conditions | No |
| `otp_verified` | Entered the one-time code sent by email | Yes: `channel`, `otp_code_id` |
| `certificate_download` | Downloaded the certificate | No |

Two events identify the verified one-time code by its record ID (`otp_code_id`) in `details`; the code itself is not included:

* `otp_verified`: `{"channel": "email", "otp_code_id": "<uuid>"}`
* `document_finished`: `{"otp_code_id": "<uuid>"}`, present when the finishing session was linked to a verified code

### Field interactions

Field interactions are tracked as `field_interaction` events. The `details` object contains the specific action and field metadata.

| Action | Description |
| - | - |
| `field_focused` | Selected a field |
| `field_completed` | Completed a field for the first time |
| `field_modified` | Modified an existing field value |
| `field_cleared` | Cleared a field value |
| `field_blur` | Finished editing a field |

The `details` object for field interactions includes:

| Field | Type | Description |
| - | - | - |
| `field_type` | `string` | Type of field (signature, text, date, etc.) |
| `action` | `string` | The specific action from the table above |
| `interaction_count` | `integer` | Number of times this field has been interacted with |
| `value_length` | `integer` | Length of the field value (when applicable) |
| `time_spent_ms` | `integer` | Time spent on the field in milliseconds (when applicable) |

### Navigation

| Event | Description | Has `details` |
| - | - | - |
| `page_viewed` | Viewed a specific page | Yes — `page_number` |
| `document_scrolled` | Scrolled to a page | Yes — `page_number` |
| `navigation_action` | Navigated the document | Yes — `action` (`next_page`, `prev_page`, `go_to_page`) |
| `zoom_changed` | Changed zoom level | No |
| `modal_interaction` | Opened or closed a dialog | Yes — `modal_type`, `action` |

### Organization seals

Firma.dev records these events for an [organization seal](/guides/organization-seals) on the request when it is applied, paused, swapped, or repinned.

| Event | Description | Has `details` |
| - | - | - |
| `organization_seal_applied` | organization seal applied | Yes: `seal_id`, `seal_name`, `display_name`, `authority_name`, `company_name`, `signatory_name`, `signatory_title_attested`, `version`, `order`, `trigger` (`at_send` or `completion`) |
| `organization_seal_paused` | organization seal paused | Yes: `reason` (`seal_revoked_stop_pending` or `seal_integrity_mismatch`), `seal_id`, `seal_name`, `order` |
| `organization_seal_swapped` | organization seal swapped | Yes: `from_seal_id`, `from_name`, `to_seal_id`, `to_name`, `order` |
| `organization_seal_repinned` | organization seal repinned | Yes: `prior_pinned_seal_id`, `new_seal_id` |

### Admin activity

Admin events use `event: "activity"` with a human-readable `description` field that describes the action taken (e.g., "Created signing request via API", "Sent signing request", "Cancelled signing request").


# API Authentication & JWT Tokens
Source: https://docs.firma.dev/guides/authentication

Learn how to authenticate API requests with API keys and use JWT tokens for embedded template and signing request editors

# API Authentication & JWT Tokens

The Firma API uses two authentication methods: API key authentication for server-to-server requests, and JWT tokens for embedding the template and signing request editors in your application.

## API Key Authentication

All API endpoints require authentication using an API key in the `Authorization` header.

### How it Works

Your API key authenticates your requests and determines which workspace resources you can access. Each workspace has its own unique API key that you can retrieve via the [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) endpoint.

**Protected Workspace**: Every company account has one protected workspace that cannot be deleted. This protected workspace holds the main API key for your account, which has access to all workspace, API key, company/account, and webhook endpoints. Use this key for account-wide operations or when you need to manage multiple workspaces.

### Test Mode (Live vs Test Keys)

Each workspace has **two** API keys: a **live** key and a **test** key. Test mode is determined by which key you send — there is no separate flag or parameter.

* Requests authenticated with the **test** key do **not** consume credits, and any signing requests they create are flagged as test and watermarked.
* Requests authenticated with the **live** key run normally and consume credits.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and by the [Get Workspace](/api-reference/v01.24.00/workspaces/get-a-workspace) and List Workspaces endpoints. Use the test key while integrating, then switch to the live key for production.

You can rotate each key type independently: pass `key_type` (`"live"` or `"test"`, default `"live"`) to the [regenerate](/api-reference/v01.24.00/workspaces/regenerate-workspace-api-key) and [expire](/api-reference/v01.24.00/workspaces/expire-pending-api-keys) endpoints. Rotating one type does not affect the other.

> [!NOTE]
>
> Test keys are full credentials with the same access scope as live keys — keep them server-side and never expose them in client code. The only difference is billing and watermarking behavior.

### API Key Rotation

You can regenerate API keys for non-protected workspaces to enhance security. When you regenerate a key:

1. **A new API key is created immediately** and returned in the response
2. **Old keys are set to expire in 24 hours** - they continue working during this grace period
3. **You can manually expire old keys early** once you've verified the new key works

> [!NOTE]
>
> **Protected workspace keys cannot be regenerated** via the API. This prevents accidental lockouts from your account. Contact support if you need to rotate your protected workspace key.

#### Regenerate API Key

Generate a new API key for a workspace. The old key will automatically expire after 24 hours:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/regenerate`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log('New API key:', result.new_key);
// Store the new key securely
```

**Response:**

```json theme={null}
{
  "message": "API key regenerated. Old keys will expire in 24 hours.",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "new_key": "firma_api_abc123xyz...",
  "expiring_keys": [
    {
      "id": "old-key-uuid",
      "expires_at": "2025-12-19T10:30:00Z"
    }
  ]
}
```

#### Expire Old Keys Early

After verifying your new key works, you can immediately expire all pending keys:

```javascript theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}/api-key/expire`,
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const result = await response.json();
console.log(`Expired ${result.expired_count} key(s)`);
```

**Response:**

```json theme={null}
{
  "message": "Expired 1 pending API key(s)",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "expired_count": 1,
  "expired_keys": ["old-key-uuid"]
}
```

**Best Practice for Key Rotation:**

1. Call the regenerate endpoint to get a new key
2. Update your application configuration with the new key
3. Test that the new key works correctly
4. Call the expire endpoint to immediately invalidate old keys
5. Monitor for any errors indicating services still using the old key

> [!WARNING]
>
> **Never expose your API key in frontend code or client-side applications.** API keys should only be used in secure backend services. Always store them as environment variables.

### Header Format

The API key can be sent in two ways:

1. **Direct format** (recommended for simplicity):

```bash theme={null}
Authorization: your-api-key-here
```

2. **Bearer token format** (optional):

```bash theme={null}
Authorization: Bearer your-api-key-here
```

Both formats are accepted. The Bearer prefix is optional but not required.

### Code Examples

```bash cURL theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);

const templates = await response.json();
```

```python Python theme={null}
import os
import requests

headers = {
    'Authorization': os.environ['FIRMA_API_KEY'],
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/templates',
    headers=headers
)

templates = response.json()
```

### Error Response

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

***

## JWT Tokens for Embedded Features

JWT (JSON Web Token) tokens enable you to embed Firma's template editor and signing request editor directly in your application. These tokens are RSA-256 signed and time-limited for security.

### When to Use JWT Tokens

Use JWT tokens when you want to:

* Embed the template editor in your application for users to create/edit document templates
* Embed the signing request editor for users to customize documents before sending
* Provide secure, time-limited access to specific templates or signing requests
* Control which resources users can access without exposing your API key

> [!NOTE]
>
> **JWT tokens should always be generated from your secure backend**, never from frontend code. Your backend uses the API key to generate tokens, which are then passed to the frontend for editor initialization.

### JWT Token Types

| Token Type | Endpoint | Expiration | Use Case |
| - | - | - | - |
| **Template Token** | [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) | 24 hours | Embed template editor for creating/editing templates |
| **Signing Request Token** | [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request) | 7 days | Embed signing request editor for document customization |

### Authentication Flow

Here's how JWT authentication works for embedded features:

```mermaid theme={null}
sequenceDiagram
    participant User as User Browser
    participant Backend as Your Backend
    participant Firma as Firma API
    participant Editor as Embedded Editor

    User->>Backend: Request to edit template
    Backend->>Firma: POST /generate-template-token<br/>(with API key)
    Firma->>Backend: JWT token (24h expiry)
    Backend->>User: Return JWT token
    User->>Editor: Initialize editor with JWT
    Editor->>Firma: Authenticate with JWT
    Firma->>Editor: Grant access to template
    Editor->>User: Display editor interface
```

### Implementation Guide

#### Step 1: Generate JWT Token (Backend)

Generate a JWT token from your secure backend using your API key:

```javascript Node.js/Express theme={null}
// Backend endpoint to generate JWT for template editing
app.post('/api/get-template-token', async (req, res) => {
  const { templateId } = req.body;

  try {
    const response = await fetch(
      'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
      {
        method: 'POST',
        headers: {
          'Authorization': process.env.FIRMA_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          companies_workspaces_templates_id: templateId
        })
      }
    );

    const data = await response.json();
    
    // Return JWT to frontend (never expose API key)
    res.json({ 
      token: data.jwt,
      expiresAt: data.expires_at 
    });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});
```

```python Python/Flask theme={null}
from flask import Flask, request, jsonify
import os
import requests

app = Flask(__name__)

@app.route('/api/get-template-token', methods=['POST'])
def get_template_token():
    template_id = request.json.get('templateId')
    
    try:
        response = requests.post(
            'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
            headers={
                'Authorization': os.environ['FIRMA_API_KEY'],
                'Content-Type': 'application/json'
            },
            json={
                'companies_workspaces_templates_id': template_id
            }
        )
        
        data = response.json()
        
        # Return JWT to frontend (never expose API key)
        return jsonify({
            'token': data['jwt'],
            'expiresAt': data['expires_at']
        })
    except Exception as e:
        return jsonify({'error': 'Failed to generate token'}), 500
```

**Response:**

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "expires_at": "2025-12-18T10:00:00Z",
  "template_id": "template-uuid-here"
}
```

#### Step 2: Initialize Editor (Frontend)

Use the JWT token to initialize the embedded editor in your frontend:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Template Editor</title>
  <!-- Load the Firma Template Editor library -->
  <script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
</head>
<body>
  <div id="firma-editor-container" style="width: 100%; height: 600px;"></div>

  <script>
    async function initializeEditor(templateId) {
      // Request JWT from your backend
      const response = await fetch('/api/get-template-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ templateId })
      });

      const { token, expiresAt } = await response.json();

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

    // Initialize with your template ID
    initializeEditor('your-template-id-here');
  </script>
</body>
</html>
```

For signing request editor, use the signing request JWT endpoint and the signing request editor library:

```javascript theme={null}
// Generate signing request token from backend
const response = await fetch('/api/get-signing-request-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ signingRequestId })
});

const { token } = await response.json();

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

// Initialize signing request editor
window.FirmaSigningRequestEditor.init({
  container: '#firma-signing-request-container',
  jwt: token,
  signingRequestId: signingRequestId,
  theme: 'light',
  onSave: (data) => console.log('Signing request saved:', data),
  onSend: (data) => console.log('Signing request sent:', data),
  onError: (error) => console.error('Error:', error)
});
```

#### Step 3: Revoke JWT Token (Optional)

Revoke a JWT token when it's no longer needed:

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jwt_id: 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    })
  }
);

const result = await response.json();
// { message: "JWT revoked successfully", jwt_id: "...", revoked_at: "..." }
```

```python Python theme={null}
response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/revoke-template-token',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'jwt_id': 'a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6'
    }
)

result = response.json()
```

### JWT Security Best Practices

> [!WARNING]
>
> **Security Checklist:**
>
> 1. ✅ **Always generate JWTs from your backend** - Never expose your API key in frontend code
> 2. ✅ **Use environment variables** - Store API keys securely, never hardcode them
> 3. ✅ **Validate token expiration** - Check `expires_at` and refresh tokens as needed
> 4. ✅ **Use HTTPS only** - Never transmit tokens over unencrypted connections
> 5. ✅ **Revoke unused tokens** - Revoke JWTs when editing is complete or the session ends
> 6. ✅ **Implement token refresh** - Request new tokens before expiration for ongoing sessions
> 7. ✅ **Scope tokens appropriately** - Each JWT is tied to a specific template or signing request

***

##

***

## Related Guides

Learn more about implementing embedded features and working with the API:

* [Embeddable Template Editor](/guides/embeddable-template-editor) - Complete guide to embedding the template editor
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Embed signing request customization
* [Sending Signing Requests](/guides/sending-signing-request) - Send documents for signature
* [Webhooks](/guides/webhooks) - Subscribe to real-time events

## API Reference

Key authentication and JWT management endpoints:

**API Key Management:**

* [Get Workspace](/api-reference/v01.15.00/workspaces/get-a-workspace) - Retrieve workspace API key
* [Regenerate Workspace API Key](/api-reference/v01.15.00/workspaces/regenerate-workspace-api-key) - Generate new API key
* [Expire Pending API Keys](/api-reference/v01.15.00/workspaces/expire-pending-api-keys) - Immediately expire old keys

**JWT Token Management:**

* [Generate JWT Token for Embedding Templates](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates)
* [Generate JWT Token for Signing Request](/api-reference/v01.15.00/jwt-management/generate-jwt-token-for-signing-request)
* [Revoke Template JWT Token](/api-reference/v01.15.00/jwt-management/revoke-template-jwt-token)
* [Revoke Signing Request JWT Token](/api-reference/v01.15.00/jwt-management/revoke-a-signing-request-jwt-token)

**Getting Started:**

* [Get Company Information](/api-reference/v01.15.00/company/get-company-information)
* [Create Template](/api-reference/v01.15.00/templates/create-template)
* [Create Signing Request](/api-reference/v01.15.00/signing-requests/create-signing-request)


# Base44
Source: https://docs.firma.dev/guides/base44-integration

Add legally binding e-signatures to any Base44 app using backend functions or a workspace-level OpenAPI integration.

Firma lets you add legally binding e-signatures to any Base44 application. Use Base44 backend functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Backend functions** (per-app) — Write TypeScript functions that call the Firma REST API directly. Best for single apps or custom logic.
2. **Custom OpenAPI integration** (workspace-level) — Import the Firma OpenAPI spec once and let every app in your workspace call Firma endpoints through `base44.integrations.custom.call()`. Best for teams running multiple apps.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Base44 app on the [Builder plan](https://base44.com/pricing) or higher (required for backend functions and custom integrations)
* At least one Firma template with signing fields configured

## Path 1: Backend functions

This is the most flexible approach. You write TypeScript functions inside your Base44 app that call the Firma REST API directly.

### Step 1: Store your API key as a secret

1. Open your app in the Base44 editor
2. Go to **Dashboard → Secrets**
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions where secrets are kept secure.

### Step 2: Create a backend function to send signing requests

Create a new function under **Dashboard → Code → Functions**, or ask the Base44 AI chat to generate one.

This example creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const user = await base44.auth.me();

  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY");

  // Create and send a signing request from a template in one call
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the function to your app UI

Call the backend function from your frontend using the Base44 SDK:

```typescript theme={null}
import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendSigningRequest", {
  template_id: "your-template-id",
  signer_email: "alice@example.com",
  signer_first_name: "Alice",
  signer_last_name: "Johnson",
});
```

You can also ask the Base44 AI chat to wire this up — for example: *"When the user clicks 'Send Contract', call the sendSigningRequest function with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, set up a Firma webhook that points to a Base44 backend function.

1. Create a new backend function to handle incoming webhook events
2. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your function's URL: `https://<your-app-domain>/functions/<function-name>`
3. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your app's database or trigger the next step
    // in your workflow using the Base44 entities SDK
  }

  return Response.json({ received: true });
});
```

## Path 2: Custom OpenAPI integration

If your workspace has multiple apps that need e-signatures, register Firma as a shared workspace integration using the OpenAPI spec. You configure authentication once and every app can call Firma endpoints without writing backend functions.

### Step 1: Add the integration

1. Click your **profile icon** at the top right of your workspace
2. Go to **Settings → Integrations**
3. Click **New Integration**
4. Select **From URL** and enter the Firma OpenAPI spec URL:

```text theme={null}
https://docs.firma.dev/api-reference/v01.15.00/openapi-v01.15.00.json
```

> [!NOTE]
>
> The spec URL includes the API version number. Check the [API changelog](/guides/api-changelog) for the latest version.

5. Click **Continue**

### Step 2: Select endpoints

Select the endpoints your apps will need. Common choices:

* `POST /signing-requests` — Create a signing request from a template or document
* `POST /signing-requests/create-and-send` — Create and send in one call
* `GET /signing-requests/{id}` — Check status
* `GET /signing-requests` — List signing requests
* `POST /templates/{id}/duplicate` — Duplicate a template into a signing request
* `GET /templates` — List available templates

You can select up to 30 endpoints.

### Step 3: Configure authentication

1. Set the **Base URL** to `https://api.firma.dev/functions/v1/signing-request-api`
2. Under **Custom Headers**, click **Add Header**
3. Set the header name to `Authorization` and paste your Firma API key as the value

Base44 stores this as an encrypted workspace secret. It never reaches the browser.

### Step 4: Use in your apps

Once configured, any app in the workspace can call Firma endpoints using the SDK:

```typescript theme={null}
const result = await base44.integrations.custom.call(
  "firma",
  "post:/signing-requests/create-and-send",
  {
    payload: {
      template_id: templateId,
      recipients: [
        {
          first_name: "Alice",
          last_name: "Johnson",
          email: "alice@example.com",
          designation: "Signer",
          order: 1,
        },
      ],
    },
  }
);
```

You can also ask the Base44 AI chat to wire up Firma calls — it will detect the workspace integration and use it automatically.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API, load it in an iframe inside your Base44 app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Base44 account. This lets the Base44 AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Account Settings → MCP Connections**
2. Add a new MCP server with the URL: `https://docs.firma.dev/mcp`

This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Bolt.new
Source: https://docs.firma.dev/guides/bolt-new-integration

Add legally binding e-signatures to any Bolt.new app using Next.js API routes, Netlify serverless functions, or Supabase Edge Functions.

Firma lets you add legally binding e-signatures to any application built with Bolt.new. Bolt.new runs a full Node.js environment in your browser, so integrating the Firma API works like any standard Node.js project. This guide covers three integration paths depending on how you deploy.

1. **Path 1: Next.js API routes (full-stack)** — The most common Bolt.new pattern. Server-side API routes proxy calls to Firma and keep your API key out of client code. Best for apps that stay on Bolt Cloud or deploy anywhere.
2. **Path 2: Netlify serverless functions** — Bolt has built-in Netlify deployment. Serverless functions handle Firma API calls at the edge without managing a server. Best for static frontends that need a lightweight backend.
3. **Path 3: Supabase Edge Functions** — If your Bolt app already uses Supabase for auth and database, you can call Firma from Edge Functions and track signing status in Postgres. See the [full Supabase integration guide](/guides/supabase-integration).

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Bolt.new account (a paid plan is recommended for private projects and custom deployment)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Next.js API routes

This is the recommended approach for most Bolt.new projects. You scaffold a Next.js app, add a server-side API route that calls Firma, and your frontend calls that route. Your API key never touches the browser.

### Step 1: Create your project

Open [bolt.new](https://bolt.new) and prompt it to scaffold a Next.js project. You can be specific:

> "Create a Next.js app with TypeScript and Tailwind CSS. I need a page where users can enter a signer's name and email, then send a contract for signing via an external API."

Bolt will generate the project structure, install dependencies, and start the dev server.

### Step 2: Add your Firma API key

For local development in the Bolt WebContainer, create a `.env.local` file in the root of your project. You can ask Bolt to create it, or add it manually in the file tree:

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in client-side code. Environment variables prefixed with `NEXT_PUBLIC_` are visible in the browser. Keep `FIRMA_API_KEY` without that prefix so it stays server-side only.

For Bolt Cloud deployments, store the key as a secret instead: click the database icon at the top of the editor, open the **Secrets** tab, and create a secret named `FIRMA_API_KEY`.

### Step 3: Create an API route to send signing requests

Create a new file at `app/api/send-signing-request/route.ts` (or ask Bolt to generate it). This route receives signer details from your frontend and calls the Firma API server-side:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Call the API route from your frontend

In your React component, call the API route when the user submits the form:

```typescript theme={null}
const handleSendContract = async () => {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();

  if (response.ok) {
    console.log("Signing request sent:", data.signing_request_id);
  }
};
```

You can also ask Bolt's AI chat to wire this up: *"When the user clicks 'Send Contract', call my `/api/send-signing-request` endpoint with the template ID, signer email, and name from the form fields."*

### Step 5: Deploy

**Bolt Cloud:** Click **Publish** in the top-right corner of the editor. Bolt assigns a random `*.bolt.host` URL you can customize afterward. Store `FIRMA_API_KEY` via the database icon → **Secrets** tab so your API routes can read it.

**Netlify:** Click the gear icon → **All project settings** → **Domains & Hosting**, then select **Netlify** from the provider dropdown and click **Publish**. After deploying, add `FIRMA_API_KEY` in Netlify's dashboard under **Site Settings → Environment Variables**.

**Vercel or other hosts:** Export the project to GitHub, then connect the repository to your host. Add `FIRMA_API_KEY` as an environment variable in your host's dashboard.

## Path 2: Netlify serverless functions

If your Bolt project uses a framework without built-in API routes (React with Vite, plain HTML, Astro in static mode), Netlify serverless functions give you a backend without restructuring your app.

### Step 1: Create the function directory

Create a directory at `netlify/functions/` in the root of your Bolt project. Netlify automatically detects and deploys functions from this path.

### Step 2: Add the signing request function

Create `netlify/functions/send-signing-request.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export const handler: Handler = async (event) => {
  if (event.httpMethod !== "POST") {
    return { statusCode: 405, body: "Method not allowed" };
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    JSON.parse(event.body || "{}");

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  return {
    statusCode: response.ok ? 200 : response.status,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(
      response.ok
        ? { signing_request_id: data.id, status: "sent" }
        : { error: data }
    ),
  };
};
```

### Step 3: Call the function from your frontend

Netlify functions are available at `/.netlify/functions/<function-name>`:

```typescript theme={null}
const response = await fetch("/.netlify/functions/send-signing-request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "your-template-id",
    signer_email: "alice@example.com",
    signer_first_name: "Alice",
    signer_last_name: "Johnson",
  }),
});
```

### Step 4: Configure environment variables and deploy

1. In Bolt, click the gear icon → **All project settings** → **Domains & Hosting** and select **Netlify**
2. Click **Publish** to deploy
3. In Netlify's dashboard, go to **Site Settings → Environment Variables**
4. Add `FIRMA_API_KEY` with your Firma API key as the value

> [!WARNING]
>
> During local development in Bolt's WebContainer, Netlify functions won't run natively. You can test your function logic by temporarily creating an equivalent API route, or by deploying to Netlify and testing against the live URL.

## Path 3: Supabase Edge Functions

If your Bolt app uses Supabase for authentication and database, you can handle Firma API calls through Supabase Edge Functions and track signing request status in Postgres.

This path is covered in detail in the [Supabase integration guide](/guides/supabase-integration). It walks through storing your API key as a Supabase secret, creating Edge Functions for sending signing requests and handling webhooks, and setting up a `signing_requests` table with Row Level Security.

To connect Supabase in Bolt, use the built-in Supabase integration or ask Bolt's AI chat: *"Connect this project to Supabase and add the Supabase client library."*

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to your app. The setup depends on which path you chose.

### Next.js API route

Create `app/api/firma-webhook/route.ts`:

```typescript theme={null}
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification,
    // or trigger the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

### Netlify serverless function

Create `netlify/functions/firma-webhook.ts`:

```typescript theme={null}
import type { Handler } from "@netlify/functions";

export const handler: Handler = async (event) => {
  const payload = JSON.parse(event.body || "{}");
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ received: true }),
  };
};
```

### Register the webhook

In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to your endpoint:

* **Next.js (Bolt Cloud):** `https://your-app.bolt.host/api/firma-webhook`
* **Next.js (Netlify):** `https://your-site.netlify.app/api/firma-webhook`
* **Netlify function:** `https://your-site.netlify.app/.netlify/functions/firma-webhook`

Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types, payload structure, and signature verification.

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Bolt app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

In a React component:

```typescript theme={null}
interface SigningEmbedProps {
  signingRequestUserId: string;
}

export default function SigningEmbed({ signingRequestUserId }: SigningEmbedProps) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: "none" }}
      allow="camera;microphone;clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to Bolt.new. This lets the Bolt AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. From the Bolt chatbox, click the **plus icon**
2. Select **Connectors**, then **Manage connectors**
3. Click **Add custom connector**
4. Set a descriptive name (e.g., "Firma Docs")
5. Enter the server URL: `https://docs.firma.dev/mcp`
6. Choose the transport type and authentication (none is required for the public docs server)
7. Click **Add**

You can toggle the connector on or off per project via the plus icon → **Connectors** menu inside any project. This is for the build experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Supabase integration](/guides/supabase-integration) — full Supabase + Firma walkthrough
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# ChatGPT
Source: https://docs.firma.dev/guides/chatgpt-integration

Add legally binding e-signatures to any ChatGPT-powered app using function calling, the Codex CLI, or ChatGPT connectors.

Firma lets you add legally binding e-signatures to anything built on OpenAI. Use the Responses API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to Codex CLI so the AI generates accurate integration code, or add Firma as a ChatGPT connector so you can manage signing requests from the ChatGPT desktop app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An OpenAI API key (for function calling), or a ChatGPT Plus/Pro/Enterprise account (for Codex CLI and connectors)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the OpenAI API itself, which uses `Bearer` tokens.

## Getting started

**Function calling**

Function calling lets a GPT model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, the model returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your OpenAI API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
OPENAI_API_KEY=your_openai_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Using the OpenAI Responses API (recommended for new projects):

```javascript theme={null}
import OpenAI from "openai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "send_signing_request",
    description:
      "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
    parameters: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A descriptive name for the signing request.",
        },
        template_id: {
          type: "string",
          description: "The ID of the Firma template to send.",
        },
        signer_email: { type: "string" },
        signer_first_name: { type: "string" },
        signer_last_name: { type: "string" },
      },
      required: [
        "name",
        "template_id",
        "signer_email",
        "signer_first_name",
        "signer_last_name",
      ],
      additionalProperties: false,
    },
    strict: true,
  },
];

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) return JSON.stringify({ error: data });

  return JSON.stringify({
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  });
}

export async function handleUserMessage(userText) {
  let input = [{ role: "user", content: userText }];

  let response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  input.push(...response.output);

  for (const item of response.output) {
    if (item.type !== "function_call") continue;
    if (item.name === "send_signing_request") {
      const args = JSON.parse(item.arguments);
      const result = await sendSigningRequest(args);
      input.push({
        type: "function_call_output",
        call_id: item.call_id,
        output: result,
      });
    }
  }

  response = await openai.responses.create({
    model: "gpt-4.1",
    tools,
    input,
  });

  return { text: response.output_text };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message:

```javascript theme={null}
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import json
import requests
from openai import OpenAI

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "send_signing_request",
        "description": "Send a document for e-signature via Firma.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "A descriptive name for the signing request."},
                "template_id": {"type": "string"},
                "signer_email": {"type": "string"},
                "signer_first_name": {"type": "string"},
                "signer_last_name": {"type": "string"},
            },
            "required": [
                "name",
                "template_id",
                "signer_email",
                "signer_first_name",
                "signer_last_name",
            ],
            "additionalProperties": False,
        },
        "strict": True,
    },
]

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return json.dumps(r.json())

input_list = [{"role": "user", "content": "Send the NDA to bob@example.com (Bob Smith)."}]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = execute(args)
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": result,
        })

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input=input_list,
)
print(response.output_text)
```

**Codex CLI via MCP**

OpenAI's Codex CLI is a terminal-based coding agent that supports MCP servers. Connecting Firma's MCP servers lets the agent build Firma integrations and operate on your Firma data.

### Step 1: Install Codex CLI

```bash theme={null}
npm i -g @openai/codex
```

Or via Homebrew:

```bash theme={null}
brew install codex
```

### Step 2: Add the Firma MCP servers

Edit your global config at `~/.codex/config.toml`, or create a project-scoped `.codex/config.toml`:

```toml theme={null}
[mcp_servers.firma-api]
url = "https://mcp.firma.dev/mcp"

[mcp_servers.firma-docs]
url = "https://docs.firma.dev/mcp"
```

Or add them via the CLI:

```bash theme={null}
codex mcp add firma-api --url https://mcp.firma.dev/mcp
codex mcp add firma-docs --url https://docs.firma.dev/mcp
```

On first use of a Firma API tool, Codex CLI will walk you through signing in via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 3: Use Firma from Codex CLI

Once connected, ask Codex CLI to build integrations or operate on your data:

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code.

**ChatGPT connectors**

The ChatGPT desktop app supports MCP servers via connectors. This lets you manage Firma signing requests, templates, and workspaces directly from the ChatGPT chat interface.

### Step 1: Enable Developer Mode

Open ChatGPT settings and navigate to **Settings > Connectors > Advanced > Developer Mode**. Developer Mode is available on Plus, Pro, Business, Enterprise, and Education plans.

### Step 2: Add the Firma MCP servers

Click **Add custom connector** and add:

* **Firma API** - URL: `https://mcp.firma.dev/mcp`
* **Firma Docs** - URL: `https://docs.firma.dev/mcp`

On first connection to the Firma API server, you will be prompted to authenticate with your Firma account via OAuth.

### Step 3: Use Firma from ChatGPT

With the connectors active, you can ask ChatGPT to manage your Firma account:

* "List all my Firma templates"
* "Send the NDA template to [alice@example.com](mailto:alice@example.com) for signing"
* "What signing requests are pending in my Sales workspace?"
* "Show me the audit trail for signing request X"

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app:

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to send documents. The MCP servers are what you and Codex CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send.
* **Validate before sending.** For higher-stakes documents, use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of the OpenAI API, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Claude Code
Source: https://docs.firma.dev/guides/claude-code-integration

Add legally binding e-signatures to any project using Claude Code with Firma's MCP servers.

Firma lets you add legally binding e-signatures to anything you build with Claude Code. Connect Firma's MCP servers and Claude Code can generate accurate Firma integration code, manage your signing requests, and operate on your Firma data directly from the terminal or your IDE.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Claude Code installed ([CLI](https://docs.anthropic.com/en/docs/claude-code), [VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code), or [JetBrains plugin](https://plugins.jetbrains.com/plugin/claude-code))
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

### Step 1: Add the Firma MCP servers

Add both Firma MCP servers to your project settings. In your project root, create or edit `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Alternatively, add them to your user settings at `~/.claude/settings.json` to make them available across all projects.

* **firma-api** gives Claude Code direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** gives Claude Code access to Firma's full documentation so it generates accurate integration code.

Restart Claude Code after saving the config. On first use of a Firma API tool, Claude Code will walk you through signing in with your Firma account via OAuth.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Step 2: Use Firma from Claude Code

Once connected, you can ask Claude Code to build Firma integrations or operate on your data:

**Generate a backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**List your signing requests:**

```text theme={null}
List all pending signing requests in my default workspace.
```

**Send a signing request:**

```text theme={null}
Create a signing request from the NDA template and send it to jane@example.com
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells Claude Code to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## What Claude Code generates

When you ask Claude Code to build a Firma integration, the generated backend code should look like this:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend where secrets are kept secure.

## Webhook integration

To track signing events in real time, ask Claude Code to add a webhook handler:

```text theme={null}
Using the Firma docs, create a webhook handler that receives Firma events.
When signing_request.completed fires, update the contract record in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use `firma-docs` when building, `firma-api` when operating.** The docs server helps Claude Code write correct integration code. The API server lets it manage signing requests, templates, and workspaces directly.
* **Pass `template_id` explicitly.** Templates are the safest way to constrain what the agent can send.
* **Validate before sending.** For higher-stakes documents, ask Claude Code to create a draft with `POST /signing-requests`, then confirm before calling `POST /signing-requests/{id}/send`.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# Cloudflare
Source: https://docs.firma.dev/guides/cloudflare-integration

Add legally binding e-signatures to Cloudflare Workers or Pages apps using the Firma API.

Firma lets you add legally binding e-signatures to any application running on Cloudflare. Call the Firma API from Workers or Pages Functions to create templates, send signing requests, and track completions via webhooks.

This guide covers two integration paths:

1. **Workers** — Standalone serverless functions that call the Firma REST API. Best for APIs, microservices, or apps that don't use Cloudflare Pages.
2. **Pages Functions** — File-based serverless functions that deploy alongside your Cloudflare Pages site. Best if you already have a Pages project and want to keep everything in one repo.

Both paths use the same Firma API endpoints. The difference is how you structure and deploy your code.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* The [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) installed (`npm install -g wrangler`)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Choose your path

**Workers**

### Step 1: Create a Worker project

If you don't have a Workers project yet, scaffold one:

```bash theme={null}
npm create cloudflare@latest -- firma-signing
```

Select **"Hello World" Worker** when prompted, then choose JavaScript or TypeScript. Once scaffolding completes:

```bash theme={null}
cd firma-signing
```

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted secret. Wrangler will prompt you to paste the value:

```bash theme={null}
wrangler secret put FIRMA_API_KEY
```

Never hardcode your API key in source files. Secrets are encrypted at rest and injected into your Worker's `env` binding at runtime.

### Step 3: Create a Worker to send signing requests

Replace the contents of `src/index.js` (or `src/index.ts` if you chose TypeScript) with the following. This Worker accepts a POST request with signer details, calls the Firma `create-and-send` endpoint, and returns the signing request ID.

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export default {
  async fetch(request, env) {
    if (request.method === "OPTIONS") {
      return new Response(null, {
        headers: {
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "POST, OPTIONS",
          "Access-Control-Allow-Headers": "Content-Type",
        },
      });
    }

    if (request.method !== "POST") {
      return Response.json({ error: "Method not allowed" }, { status: 405 });
    }

    const { name, template_id, signer_email, signer_first_name, signer_last_name } =
      await request.json();

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: env.FIRMA_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return Response.json({ error: data }, { status: response.status });
    }

    return Response.json({
      signing_request_id: data.id,
      status: "sent",
    });
  },
};
```

> [!TIP]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Deploy

```bash theme={null}
wrangler deploy
```

Wrangler will output your Worker's URL (something like `https://firma-signing.<your-subdomain>.workers.dev`). Your frontend can now POST signer details to that URL.

### Webhook handling

To track when documents are signed, create a second Worker that receives Firma webhook events. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to this Worker's URL.

```javascript theme={null}
export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const payload = await request.json();
    const { type, data } = payload;

    if (type === "signing_request.completed") {
      const signingRequestId = data.signing_request.id;
      console.log(`Signing request ${signingRequestId} completed`);
    }

    if (type === "signing_request.recipient.signed") {
      const recipientEmail = data.recipient?.email;
      console.log(`${recipientEmail} signed the document`);
    }

    return Response.json({ received: true });
  },
};
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

**Pages Functions**

### Step 1: Set up your Pages project

If you already have a Cloudflare Pages project, skip to the next step. Otherwise, create one:

```bash theme={null}
mkdir firma-app && cd firma-app
npm init -y
mkdir public functions
echo "<h1>Firma App</h1>" > public/index.html
```

Pages Functions live in the `/functions` directory. Each file maps to a URL path automatically, so `functions/api/send-signing-request.js` becomes `/api/send-signing-request`.

### Step 2: Store your API key as a secret

Add your Firma API key as an encrypted Pages secret:

```bash theme={null}
wrangler pages secret put FIRMA_API_KEY --project-name your-project-name
```

Alternatively, go to **Cloudflare Dashboard → Pages → your project → Settings → Environment variables** and add `FIRMA_API_KEY` as an encrypted variable.

### Step 3: Create a Pages Function to send signing requests

Create a new file at `functions/api/send-signing-request.js`:

```javascript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function onRequestPost(context) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await context.request.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: context.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return Response.json({ error: data }, { status: response.status });
  }

  return Response.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!TIP]
>
> Pages Functions export named handlers per HTTP method: `onRequestPost`, `onRequestGet`, etc. If you need to handle multiple methods, export `onRequest` and check `context.request.method` inside.

### Step 4: Deploy

If your Pages project is connected to a Git repo, push your changes and Cloudflare deploys automatically. For manual deploys:

```bash theme={null}
wrangler pages deploy public --project-name your-project-name
```

Your function is now live at `https://your-project.pages.dev/api/send-signing-request`.

### Webhook handling

Create a second Pages Function at `functions/api/firma-webhook.js` to handle incoming Firma webhook events. Register this URL in the Firma dashboard under **Settings → Webhooks**.

```javascript theme={null}
export async function onRequestPost(context) {
  const payload = await context.request.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return Response.json({ received: true });
}
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to. If you use an AI assistant while building your Cloudflare integration, connecting the MCP server lets it search Firma documentation and generate accurate API calls.

Add the MCP server URL to your tool's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the development experience only and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Complete Setup Guide
Source: https://docs.firma.dev/guides/complete-setup-guide

This comprehensive guide shows you how to build and launch a complete e-signature workflow inside your own application using Firma.dev. We'll cover everything from account setup to embedded signing, workspace management, templates, and credit-based billing.

## How to Integrate Embedded E-Signatures in Your App: Step-by-step guide to setting up Firma.dev workspaces, templates, signing requests, and embedded signing

Whether you're building for one internal use case or scaling across thousands of customers in a SaaS product, Firma offers the flexibility and pricing to move quickly.

## Introduction

Firma.dev is a lightweight, developer-first API that makes it easy to integrate e-signatures into your app. It's especially well-suited for SaaS platforms that need to support customer-specific templates and signing flows without building a document pipeline from scratch.

### Why developers choose Firma

* **Pay-as-you-go** pricing at €0.049/envelope (or about 5 cents USD) - no subscriptions, no hidden fees
* **Fast integration** with embeddable signing and template editors
* **Workspace isolation** to separate templates and usage per customer
* **Compliance-aligned** with ESIGN, UETA, eIDAS, GDPR, HIPAA, and more

This guide walks through everything you need to go from your first API key to a live signing flow, with references to key implementation docs and best practices along the way.

***

## Prerequisites

Before getting started, make sure you have the following:

* A [Firma account](https://www.firma.dev) - you can sign up for free with no credit card required.
* A PDF document you want to use in your signing flow.
* Familiarity with REST APIs and webhooks - most of your interaction with Firma will be API-based.
* An app environment where you can test API calls - **Node.js or PHP** are ideal for this quickstart guide, but any server-side environment will work just as well.

Firma is built with regulatory alignment in mind. You can use it confidently in workflows governed by:

* **ESIGN Act / UETA** (USA)
* **eIDAS SES/AdES** (EU/UK)
* **HIPAA** (healthcare)
* **GDPR** (personal data protection)

***

## Create Your Account & Get Your API Key

To begin integrating Firma, you'll first need to create an account and access your API key:

1. Visit [firma.dev](https://firma.dev) and create an account.
2. Once you're logged in, go to your dashboard. You'll find your API key listed there.
3. Firma provides **one unified environment** with envelopes priced so low (just **€0.049 each**) that testing and iterating costs virtually nothing.

### Making API Calls

You'll pass your API key via the `Authorization` header in all requests:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/... \
  -H "Authorization: your_api_key_here"
```

### Start in test mode

Each workspace has two API keys: a **live** key and a **test** key. While you build your integration, use the **test** key — requests authenticated with it don't consume credits and produce test-flagged, watermarked documents, so you can iterate freely. Switch to the live key when you're ready for production.

Both keys are returned when you create a workspace (`api_key` = live, `test_api_key` = test) and from the Get Workspace endpoint, and both appear in your dashboard. See [Authentication](/guides/authentication) for how test mode works.

```bash theme={null}
# Test mode — no credits charged, output watermarked
curl https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_test_api_key_here"
```

***

## Create Workspaces (For SaaS or Multi-Customer Apps)

In Firma, **workspaces** provide isolated environments for your customers. Each workspace has its own:

* Templates
* Signing activity
* Usage and billing metrics
* **Security key** for scoped API access

This makes workspaces essential for SaaS platforms that manage customer-specific documents and flows. You'll typically create a new workspace for each customer account.

### Workspace Security and Isolation

Each workspace in Firma comes with its own **workspace-specific API key**, which is used to securely scope actions to that workspace. This ensures that templates, signing requests, and envelopes created within a workspace cannot cross over into others - maintaining strong logical separation across your customers.

### Creating a Workspace

Here's how to create a workspace via the API:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc."
  }'
```

The response will include two important values: `id` and `api_key`. These correspond to the workspace's unique identifier and its scoped security key. You'll use both to manage activity tied to that specific customer.

📘 [Creating Workspaces Guide](/guides/creating-workspaces)

📘 [Workspace Settings Guide](/guides/workspace-settings)

***

## Create a Template

A **template** defines a reusable document workflow. It includes the structure of the document, signer roles, and field placements (like signature boxes, initials, and dates). This is especially powerful when you're automating contracts, agreements, or internal documents.

You must start with a static PDF file - this becomes the basis of your template.

### Two Ways to Create Templates

#### Option 1: Embedded Template Editor

The embedded template editor allows your internal team or your customers to visually place fields and configure signer roles inside your app. It's easy to integrate and removes the need for technical users to define layouts via code.

📘 [Embedded Template Editor Guide](/guides/embeddable-template-editor)

#### Option 2: Create via API

If you're building programmatically, you can use the API to define templates. You'll upload your document and define signer roles and field coordinates manually.

Example template creation:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/templates \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement",
    "document": "JVBERi0xLjQK..."
  }'
```

The `document` field accepts a base64-encoded PDF or DOCX file. The response returns the template ID, which you can then use to add recipients and fields via the template editor or API.

📘 [Templates API](/api-reference/v01.15.00/templates/list-templates)

***

## Send a Signing Request

A **signing request** is the live transaction that sends a document to one or more people for signing. It's always tied to a workspace and either a template or a document upload.

You'll need to specify:

* Workspace ID
* Template ID (or raw document upload)
* Signers - each with name, email, and role
* Optional: signing order, metadata, and expiration

Example request (from a template):

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "Authorization: your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service Agreement - Jane Smith",
    "template_id": "your_template_id",
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

You can also create signing requests directly from a document (base64-encoded PDF or DOCX) instead of a template by passing `document` instead of `template_id`.

📘 [Signing Requests](/api-reference/v01.15.00/signing-requests/list-signing-requests)

### Using the embeddable signing request editor

If you would rather provide a UI to configure who the document goes to and how it is sent, instead of building the JSON payload yourself, you can embed the signing request editor in your product.

A typical flow looks like this:

* Your backend creates a signing request in the correct workspace (often in a draft state) from a template.
* Your backend generates a short-lived JWT token for that signing request using Firma's JWT endpoint.
* Your frontend loads the **embeddable signing request editor** in an iframe or dedicated view and passes it the JWT.
* Signer details (names, emails, roles) and options such as expiration or message are filled in via the UI.
* When they click **Send**, Firma updates or sends the signing request, and you can react using webhooks or `postMessage` events.

This works well for:

* Internal teams who send lots of documents but don't want to work with raw API requests.
* Customer admins in a SaaS app who should be able to manage recipients themselves without exposing your API keys.

📘 [Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor)

***

## Perform the Signing (Embedded or Redirect)

After creating a signing request, Firma will generate secure signing URLs for each signer. You can embed these URLs directly in your product or use a simple redirect.

### Option 1: Embedded Signing

Embed the signing flow within your app for a seamless experience. This is ideal if you're building a white-labeled or fully-integrated product.

📘 [Embedded Signing Guide](/guides/embeddable-signing)

### Option 2: Redirect Signing

Alternatively, you can redirect the user to Firma's hosted signing interface using the secure URL returned in the signing request response.

Once signing is complete:

* You can retrieve the signed PDF via the API
* Access the audit trail and metadata for compliance

***

## Monitor Usage & Check Credits

Firma uses a **credit-based** pricing model. Every envelope (a document sent for signing) costs just **€0.049** (or about 5 cents USD). There are no subscriptions, no minimums, and no surprise fees.

### Checking your current credit balance

To see how many credits you have left at any time, call the **Get Company Information** endpoint using your company-level API key:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: your_api_key"
```

The response includes a `credits` field, along with other information about your company. For example:

```json theme={null}
{
  "id": "company_123",
  "company_name": "Your Company",
  "credits": 17
}
```

Here, `"credits": 17` means you can send 17 more envelopes before you need to top up. You can use this value in your own admin tools to show remaining credits to your team or to block new signing requests when you get too low.

### Refilling credits

When you are close to zero credits:

* Purchase more credits from within the Firma dashboard
* Once purchased, your new balance will be reflected in the `credits` field returned by the company information endpoint
* Credits are available to all of your workspaces under that company

You can periodically poll the company endpoint to keep an eye on usage, or integrate it into internal monitoring and dashboards.

***

## Example End-to-End Flow

***

## Advanced Integration Options

### Embedded Template Editor

Let your users build and manage their own templates directly from your app interface. The embedded editor gives them full control to upload documents, place fields, and define signing logic visually.

📘 [Template Editor Guide](/guides/embeddable-template-editor)

### Webhooks

Webhooks let your backend respond to document events in real-time. You'll receive callbacks when:

* A document is viewed
* A signer completes their part
* The full document is signed and finalized

This is ideal for workflows that include CRM updates, email notifications, internal triggers, or compliance auditing.

📘 [Webhooks Guide](/guides/webhooks)

***

## Best Practices

* Use descriptive and consistent signer role names across templates
* Keep PDFs clean - remove dynamic elements and avoid interactive content
* Plan for webhook delivery retries - implement idempotency where needed
* Use test credits to explore flows before you launch
* Track usage per workspace for customer-level billing or reporting

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

## What's Next?

You've now got everything you need to implement a full, embedded e-signature workflow with Firma. Next, you can:

* Extend flows with **multi-signer** or **sequential routing**
* Apply your brand to embedded signing UIs
* Use **audit logs** for compliance needs
* Build a metrics dashboard using per-workspace usage data

Firma is purpose-built for developers who want to move fast - and scale cleanly.

[Start now](https://www.firma.dev) - at €0.049 per envelope, getting started costs virtually nothing.


# Conditional Fields
Source: https://docs.firma.dev/guides/conditional-fields

Show, hide, and require signing request fields based on the value of other fields, and group checkboxes or radio buttons with multi_group_id.

Firma fields can react to what a signer has already entered. A field can appear only after another field is filled in, become required only when a checkbox is ticked, or belong to a mutually-exclusive group of options. This guide covers `visibility_conditions`, `required_conditions`, and `multi_group_id` - the three properties that drive this behavior - along with the mistakes that most often cause them to misbehave.

## The condition model

Both `visibility_conditions` and `required_conditions` accept the same shape: a `ConditionSet`.

```typescript theme={null}
interface ConditionSet {
  logic: 'and' | 'or';
  groups: ConditionGroup[];
}

interface ConditionGroup {
  conditions: Condition[];
}

interface Condition {
  field_id: string;
  operator: ComparisonOperator;
  value?: string | number | null;
}
```

> [!WARNING]
>
> **The inner logic is the opposite of the outer logic.** `logic: "and"` combines the top-level `groups` with AND, but the `conditions` inside each group are combined with OR. `logic: "or"` does the reverse: groups are OR'd together, conditions inside each group are AND'd. This inversion is intentional - it's what lets you express "(A or B) and (C or D)" as two groups under an outer `and`, or "(A and B) or (C and D)" as two groups under an outer `or`. A single group with a single condition behaves the same either way.

### Operators

| Operator | Needs `value`? | Comparison |
| :- | :- | :- |
| `is_filled` | No | True if the referenced field has any non-empty value |
| `is_empty` | No | True if the referenced field is empty |
| `equals` | Yes | Case-insensitive string equality |
| `not_equals` | Yes | Case-insensitive string inequality |
| `contains` | Yes | Case-insensitive substring match |
| `not_contains` | Yes | Case-insensitive substring non-match |
| `greater_than` | Yes | Numeric comparison |
| `less_than` | Yes | Numeric comparison |
| `greater_than_or_equal` | Yes | Numeric comparison |
| `less_than_or_equal` | Yes | Numeric comparison |

`field_id` must reference another field assigned to the **same recipient** as the field carrying the condition. Both the signing view and the server evaluate conditions using only that recipient's own field values - a condition that references a field belonging to a different signer or approver will never resolve to a real value (see the stale-reference gotcha below). `value` accepts a string or number; omit it for `is_filled`/`is_empty`.

> [!NOTE]
>
> Limits enforced server-side: at most 20 groups per condition set, at most 20 conditions per group, `field_id` up to 100 characters, and a string `value` up to 1000 characters. These exist to bound evaluation cost, not to constrain realistic use - most condition sets use one or two groups.

## Visibility conditions

Set `visibility_conditions` on a field to control whether it's shown to the signer at all:

```json theme={null}
{
  "id": "shipping-address-field",
  "type": "text",
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "ships-to-different-address-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

A field with no `visibility_conditions` is always visible. A field with `visibility_conditions` is visible only while the condition set evaluates to true, and hidden otherwise. A hidden field is also excluded from validation - it can't block the signer from finishing, and it isn't rendered in the signing view.

## Required conditions

Set `required_conditions` to make a field's required status depend on other field values, instead of being fixed at field-creation time:

```json theme={null}
{
  "id": "reason-for-exception-field",
  "type": "text_area",
  "required": false,
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          { "field_id": "requesting-exception-checkbox", "operator": "equals", "value": "true" }
        ]
      }
    ]
  }
}
```

> [!WARNING]
>
> **`required_conditions` replaces `required` - it doesn't combine with it.** If `required_conditions` is present, the field is required exactly when the conditions evaluate to true, and the static `required` flag is ignored entirely. Setting both `required: true` and `required_conditions` does not mean "always required, and especially required under these conditions" - the top-level `required` value becomes irrelevant the moment `required_conditions` is set. Leave `required` at its default (`false`) on any field that carries `required_conditions`, so the intent in your source data matches the actual behavior.

### A hidden field is excluded from required validation

A field whose `visibility_conditions` evaluate to false is excluded from required-field validation entirely - both client-side and server-side. This means a field can have `required_conditions` that evaluate to true while being hidden, and the signer will **not** be blocked. The risk is the opposite of what you might expect: required data you intended to collect can be silently skipped if the field is hidden by its visibility conditions. The template and signing request editors surface a live warning in the field properties panel when a field's required and visibility conditions could disagree - but the check is a conservative heuristic (it flags structurally different condition sets, not just logically incompatible ones), so review any field carrying both properties by hand. The safest pattern is to make `visibility_conditions` a superset of `required_conditions`: whenever the field must be filled in, it's also on-screen.

## `multi_group_id`: linking checkboxes and radio buttons

`multi_group_id` links multiple `checkbox` or `radio_buttons` fields into one logical group. It's a UUID, not a label - and the two field types behave differently once grouped.

> [!WARNING]
>
> **`multi_group_id` must be a valid UUID.** The database column is a native Postgres `uuid` type. If you send a plain string like `"group-1"` through the public API's `fields` array (or through `anchor_tags`), field validation doesn't reject the string up front - it passes the `multi_group_id` value straight through to the insert, where Postgres rejects it with `invalid input syntax for type uuid`. That failure surfaces as a generic `500 INTERNAL` error with no indication that `multi_group_id` was the cause. Generate a real UUID (e.g. `crypto.randomUUID()` in JS, `uuid4()` in Python) and reuse the same value across every field in the group.
>
> The **template editor** in the Firma dashboard doesn't have this problem - dragging a "Linked Radio Button" onto the canvas assigns a temporary group id that the template save path converts to a real UUID for you. The **signing-request editor** does not perform this conversion, so radio groups created there can hit the same UUID error. The UUID requirement bites when you're building fields through the API or through the signing-request editor.

### Radio buttons: mutually exclusive by design

Fields of type `radio_buttons` that share a `multi_group_id` are a single-choice group: selecting one deselects every other field in the group, both in the signing UI and in how the group's required status resolves. Use this when you want the signer to pick exactly one option from a fixed set - a single field per option, all sharing one `multi_group_id`:

```json theme={null}
{
  "fields": [
    {
      "id": "plan-basic",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 10, "width": 4, "height": 4 }
    },
    {
      "id": "plan-pro",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 18, "width": 4, "height": 4 }
    },
    {
      "id": "plan-enterprise",
      "type": "radio_buttons",
      "multi_group_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "required": true,
      "recipient_id": "temp_1",
      "page_number": 1,
      "position": { "x": 10, "y": 26, "width": 4, "height": 4 }
    }
  ]
}
```

Only one field in this group can end up filled. `required: true` on a radio group means "the signer must pick one of the options" - the requirement is satisfied as soon as any single field in the group has a value.

> [!TIP]
>
> The API's `type` enum documents `radio_buttons`, but `radio` is also accepted and normalized to `radio_buttons` server-side - either spelling works.

### Checkboxes: grouped for "pick at least one," never exclusive

Fields of type `checkbox` that share a `multi_group_id` do **not** become mutually exclusive. Each checkbox in the group is still checked or unchecked independently - checking one does not uncheck the others. Grouping checkboxes only changes how the *required* status is evaluated: instead of every checkbox in the group needing to be checked, the group as a whole is satisfied once at least one checkbox in it is checked.

```json theme={null}
{
  "fields": [
    {
      "id": "contact-email",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true,
      "variable_name": "How should we reach you? (pick one or more)"
    },
    {
      "id": "contact-phone",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    },
    {
      "id": "contact-mail",
      "type": "checkbox",
      "multi_group_id": "b3e1a1a0-1e3e-4c1a-9c2a-2e6f6a1b0d1e",
      "required": true
    }
  ]
}
```

A signer can check any combination - one, two, or all three - and the requirement is met.

| | Same `multi_group_id` behavior | Requirement satisfied by |
| :- | :- | :- |
| `radio_buttons` | Mutually exclusive - selecting one clears the rest | Any one field in the group having a value |
| `checkbox` | Independent - no exclusivity | At least one field in the group being checked |
| `checkbox` (no `multi_group_id`) | N/A - standalone field | That specific field being checked |

If you actually want mutually-exclusive single-choice options rendered as checkboxes rather than circles, there's no server-side flag for that - build the group with `radio_buttons`. `multi_group_id` on `checkbox` fields is for "select any of these, but at least one," not for exclusivity.

## Combining all three

A common real-world shape: a checkbox that reveals a text field, which is itself part of a radio choice elsewhere in the document.

```json theme={null}
{
  "fields": [
    {
      "id": "opt-out-checkbox",
      "type": "checkbox",
      "required": false
    },
    {
      "id": "opt-out-reason",
      "type": "text_area",
      "required": false,
      "visibility_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      },
      "required_conditions": {
        "logic": "and",
        "groups": [
          { "conditions": [{ "field_id": "opt-out-checkbox", "operator": "equals", "value": "true" }] }
        ]
      }
    }
  ]
}
```

Here `opt-out-reason` is hidden and optional until `opt-out-checkbox` is checked, at which point it becomes both visible and required - the identical condition set on both properties keeps them in lockstep, so the field is never required while hidden.

## Gotchas

### The mandatory-field counter can go backward as the signer fills in the form

The signing view shows a "X of Y required fields completed" indicator. `Y` (the total) is computed from whichever fields are *currently* required - including any field whose `required_conditions` just became true. That means checking a box that reveals a newly-required field increases `Y` immediately, while `X` (filled count) doesn't change until the signer fills that new field in. The visible effect is the completion percentage dropping right after the signer answers a question, which reads as the counter "not updating" when it's actually doing the opposite: updating to reflect a form that just got longer.

There's no way to avoid this if a conditional field is going to add a genuine new requirement, but you can minimize the jump by placing the fields that reveal new requirements early in the document, so the "reveal" happens before the signer has made much progress rather than near the end.

### Conditions referencing a deleted or unreachable field never fire

If a `field_id` inside a condition doesn't match any field the signer can see, the evaluator treats its value as empty - the condition doesn't error, it just resolves as if that field were blank. `is_empty`, `not_equals`, and `not_contains` conditions against a missing field id evaluate to true; `is_filled`, `equals`, `contains`, and the numeric comparisons evaluate to false. A `visibility_conditions` set built entirely from stale `field_id` references (for example, `equals`/`is_filled` checks) will just make the field permanently hidden. If a field you expected to show up never does, confirm the `field_id` in its conditions still matches a real field's `id` on that same signing request, and that the referenced field wasn't removed later in a template edit.

## Next steps

* [Field Prefilling](/guides/field-prefilling) - the properties that control a field's displayed value, as distinct from whether it's shown or required
* [Sending a Signing Request](/guides/sending-signing-request) - the full recipient and field creation flow these fields live inside


# Workspaces
Source: https://docs.firma.dev/guides/creating-workspaces

Workspaces let you create isolated environments for each of your customers or business units. Every workspace has its own templates, documents, and envelope usage—so teams stay separate without extra effort.

* **Partitioned access:** Users, templates, and activity are scoped to a single workspace.
* **Usage tracking:** See envelopes sent per workspace for clean reporting.
* **Security by design:** No cross-workspace exposure of documents or data.

This makes it simple to give every customer or team their own private signing environment while you manage everything through the same API.

## Core Endpoints

Core endpoints (see the API reference for full details):

* POST `/workspaces` — create a workspace
* GET `/workspaces/{workspace_id}` — retrieve workspace details
* PUT `/workspaces/{workspace_id}` — update workspace
* GET `/workspaces` — list workspaces (pagination)
* GET `/workspace/{workspace_id}/settings` — get workspace settings
* PUT `/workspace/{workspace_id}/settings` — update workspace settings

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

You can also find dedicated reference pages under `api-reference/v01.15.00/workspaces`:

* `api-reference/v01.15.00/workspaces/create-a-new-workspace`
* `api-reference/v01.15.00/workspaces/list-workspaces`
* `api-reference/v01.15.00/workspaces/update-a-workspace`

Authentication

All requests must include an Authorization header using your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Note: never expose your primary API key to end-user browsers. For per-workspace operations that need to be initiated from the frontend, call your backend which holds the key.

## Create a workspace

Endpoint: POST `/workspaces`

Required body: `{ "name": "string" }`

Example (curl):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
```

Successful response (201) returns the `Workspace` resource, including the workspace's `api_key` (live) and `test_api_key`. Example shape:

```json theme={null}
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
```

The `api_key` is the workspace's live key and `test_api_key` is its test key. See [Authentication](/guides/authentication) for how test mode works.

Server example — Node (fetch):

```js theme={null}
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
```

Server example — Python (requests):

```py theme={null}
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()
```

## Retrieve a workspace

Endpoint: GET `/workspaces/{workspace_id}`

Example (curl):

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response: the `Workspace` resource (see example above).

## Update a workspace

Endpoint: PUT `/workspaces/{workspace_id}` — full resource replacement. Required body same as `CreateWorkspace` (e.g., `{ "name": "New name" }`).

Example (curl):

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
```

Server example — Node (fetch):

```js theme={null}
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}
```

## List workspaces

Endpoint: GET `/workspaces`

Supports `page` and `page_size` query parameters. Example:

```bash theme={null}
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
```

Response shape contains `results` (array of `Workspace`) and `pagination` metadata.

## RBAC and API key best practices

* Use scoped API keys where possible: keep a server-only master API key and create per-workspace API keys for integration partners if your platform supports it.
* Never return API keys to the browser. For operations initiated by end users, call your backend which performs the API call to Firma.
* The Firma API does not support an `Idempotency-Key` header. Store the `id` returned by the first call and check for it before retrying.

## Edge cases & troubleshooting

* Duplicate names: workspace names are display-friendly and may not be unique; use the `id` for programmatic references.
* Protected workspaces: the `protected` flag marks your company's default workspace. It cannot be deleted, and a regular API key cannot manage it through the API (`403 PROTECTED_WORKSPACE`); manage it from the dashboard.
* Owner-only workspace settings: workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner. Owners and Admins can manage webhooks, company settings, users, and signing requests.
* Rate limits & errors: inspect non-2xx responses for `{ error, code }` and surface meaningful messages to operators.
* **Rate limit exceeded (429)**: Monitor `X-RateLimit-Remaining` header and implement exponential backoff for retries.

## Next steps

* [Send signing requests](/guides/sending-signing-request) within workspaces (100 req/min)
* [Set up webhooks](/guides/webhooks) to track workspace activity (60 req/min)
* [JWT authentication](/guides/embeddable-template-editor#jwt-authentication) for embedded workflows (120 req/min)


# Cursor
Source: https://docs.firma.dev/guides/cursor-integration

Add legally binding e-signatures to any project using Cursor's AI features and the Firma API.

Firma connects to Cursor through two MCP servers: one that lets you manage signing requests, templates, and workspaces directly from the editor, and one that gives Cursor's AI access to Firma's documentation so it can generate accurate integration code. This guide covers both.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* [Cursor](https://cursor.com) installed with MCP support
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Connect the Firma Data MCP server

The Data MCP server gives Cursor direct access to the Firma API. Once connected, you can manage signing requests, templates, webhooks, and workspaces through natural language in Composer or Chat.

### One-click install

Use the one-click install button on the [Firma MCP integration page](/guides/mcp) to add the server to Cursor automatically.

### Manual setup

Add the following to your project-level config at `.cursor/mcp.json`, or to your user-level config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving. The first time you use a Firma tool, Cursor will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask Cursor things like:

* "Show me all pending signing requests in my workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Set up a webhook for signing\_request.completed events"

The Data MCP server exposes 84 tools across signing requests, templates, workspaces, webhooks, email configuration, and more. See the [full tool reference](/guides/mcp#available-tools) for the complete list.

## Connect the Firma Docs MCP server

The Docs MCP server gives Cursor's AI access to Firma's documentation. This is what enables Composer and Chat to generate accurate Firma integration code, because it can look up endpoints, request formats, and authentication details in real time instead of guessing.

Add it alongside the Data server in your `.cursor/mcp.json`. The two entries are distinct MCP servers — `firma-api` for runtime actions against the Firma API, and `firma-docs` for documentation lookups:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Cursor after saving.

> [!NOTE]
>
> **When to use which server:** The Data MCP server (`firma-api`) is for doing things (sending signing requests, managing templates). The Docs MCP server (`firma-docs`) is for building things (generating integration code with accurate API details). Most developers will want both connected.

## Generate a Firma integration with Composer

With both MCP servers connected, Cursor's Composer can generate working Firma integration code for your project. Here are example prompts that work well:

### Backend endpoint for sending signing requests

```text theme={null}
Using the Firma API docs, create a Next.js API route that:
1. Accepts a template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and status
Store the API key in an environment variable called FIRMA_API_KEY.
```

Composer will search the Firma docs, find the correct endpoint (`POST /signing-requests/create-and-send`), and generate a complete API route using the right base URL, headers, and request body format.

### Embedded signing in a React app

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, show the signing experience
in an iframe. Use the signing_request_user_id from the API response.
```

### Webhook handler for completed signatures

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our database.
```

### Full integration from scratch

```text theme={null}
I need to add e-signatures to this app. Users should be able to:
1. Pick a contract template
2. Enter the signer's name and email
3. Send the contract for signing
4. See when the contract has been signed

Use the Firma API for all of this. Check the Firma docs for
the correct endpoints and request formats.
```

## Example: Next.js API route

Here's what Composer typically generates for a Next.js signing request endpoint. You can use this as a reference or starting point:

```typescript theme={null}
// app/api/sign/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single call. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Store your API key in `.env.local` (or your project's equivalent):

```bash theme={null}
FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from server-side routes or backend functions.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Tips for working with Cursor + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Composer to query the Docs MCP server before generating code.
* **Use Agent mode for multi-file changes.** If you're adding signing to an existing app, Composer's Agent mode can create the API route, update the frontend, and add environment variables across files in one pass.
* **Test with the Data MCP server.** After generating your integration code, you can use the Data MCP server to send test signing requests directly from Cursor's chat, without leaving the editor.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) — full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Custom Domains
Source: https://docs.firma.dev/guides/custom-domains

Set up DNS records for a custom email domain, understand each verification state, and resolve DKIM selector conflicts with other providers.

Custom domains let signing request emails send from your own domain instead of Firma's default. This guide covers why that matters, exactly which DNS records you need, and how to resolve the conflicts and stuck states that come up most often.

> [!NOTE]
>
> This guide focuses on DNS mechanics and troubleshooting. For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains) in the White Labeling guide.

***

## Why set up a custom domain

**Sender reputation.** Email sent from Firma's shared sending domain carries Firma's reputation, not yours. A verified custom domain sends under your own SPF/DKIM/DMARC records, so your sending history and reputation build up independently and aren't affected by other Firma customers.

**Branding.** Recipients see signing invitations from `support@sign.yourcompany.com` by default instead of a firma.dev address. Set `email_local_part` at company or workspace level to choose a different local part.

Custom domains can be set at the company level (default for all workspaces) or per workspace (for multi-tenant apps that need a distinct domain per customer). See [Account-level vs. workspace-level domains](/guides/white-labeling#custom-email-domains) for the resolution order.

The same verified company domain can be shared by its workspaces. A workspace-specific domain overrides it only for that workspace.

***

## DNS records you'll need

Setting up a domain requires three DNS records once it's finalized, plus one TXT record earlier to prove ownership:

| Record | Purpose |
| - | - |
| TXT `_firma-verification.<domain>` | One-time proof that you control the domain, checked before Firma will touch DNS-sending setup at all |
| TXT `@` (SPF) | Authorizes Firma's sending infrastructure to send mail for your domain |
| CNAME `resend._domainkey` | DKIM key that lets receiving mail servers cryptographically verify the message wasn't altered in transit |
| TXT `_dmarc` | Tells receiving servers what to do with mail that fails SPF/DKIM (Firma sets a permissive default) |

**1. Add the domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "domain": "acme.com" }'
```

The response includes a `verification_token` and a `_firma-verification.<domain>` TXT record to add. The record's value is the raw token - no prefix or formatting.

**2. Verify ownership**

Once the TXT record is live, call `verify-ownership`. Firma looks up the record over DNS and compares it to the stored token.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**3. Finalize to get sending records**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

This registers the domain with Firma's email provider and returns the SPF, DKIM, and DMARC records to add:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

> [!WARNING]
>
> If domain finalization fails because the domain is already registered under another Resend account, see [Already using Resend for your own email?](#already-using-resend-for-your-own-email) below. The background auto-finalize job (runs within \~5 minutes) sets `status_message: "resend_conflict"` on the domain row - check the domain's status via `GET /company/domains` to detect this.

**4. Add the DNS records and verify**

Add all three records, then trigger a check:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

DNS propagation typically takes minutes but can take up to 48 hours. It's normal to call `verify-dns` more than once while records propagate.

See the [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains) for every endpoint, and [Custom email domains](/guides/white-labeling#custom-email-domains) for workspace-scoped equivalents.

***

## Already using Resend for your own email?

The single most common setup failure: **you already have this domain registered in your own Resend account** for your own transactional email (password resets, notifications, etc.).

Firma sends through its own Resend account under the hood. Resend does not allow the same domain to be registered under two different accounts at once. When Firma's background auto-finalize job detects a conflict, it sets `status_message: "resend_conflict"` on the domain row. This surfaces in the dashboard as a **Domain Conflict** badge on the domain.

> [!TIP]
>
> **The fix is always to use a subdomain.** Instead of adding `acme.com` (which you've already registered with your own Resend account), add a dedicated subdomain like `sign.acme.com` or `notify.acme.com`. A subdomain is a distinct hostname to Resend, so it can be registered and verified independently - it will not conflict with the parent domain's existing registration, and its DKIM record (`resend._domainkey.sign.acme.com`) is a different DNS name from your existing one (`resend._domainkey.acme.com`).

This is also the right pattern even if you're not using Resend directly yourself - it isolates Firma's DNS records from whatever your main domain is already doing for email, and it's what most of our customers do regardless of conflicts.

***

## Other provider conflict patterns

Beyond the direct Resend conflict above, two more general DNS constraints trip people up when a domain already sends mail through another provider (Google Workspace, Microsoft 365, SendGrid, Mailgun, Postmark, etc.):

**SPF: only one record is allowed per domain.** If `acme.com` already has an SPF TXT record for another provider (e.g. `v=spf1 include:_spf.google.com ~all`), do not add a second TXT record at `@` for Firma's `include:amazonses.com`. Two SPF records at the same name causes a permanent SPF failure (`permerror`) for **every** sender on the domain, not just Firma. Merge the mechanism into your existing record instead:

```
v=spf1 include:_spf.google.com include:amazonses.com ~all
```

**DMARC: only one policy record is meaningful per domain.** If `_dmarc.acme.com` already exists with a policy like `p=quarantine` or `p=reject`, don't add a second `_dmarc` record with Firma's default `p=none`. Multiple `_dmarc` TXT records make DMARC processing undefined for mail servers that check it. Keep your existing, stricter policy - it still applies to Firma's mail as long as SPF and DKIM pass.

**DKIM selectors from other providers generally don't collide.** Each provider uses its own CNAME selector name (Google uses `google._domainkey`, Microsoft uses `selector1._domainkey`/`selector2._domainkey`, SendGrid uses its own custom selector, and so on), so DKIM itself is rarely the issue outside the Resend-specific conflict above. If you do hit an unexpected DKIM collision with a provider other than Resend, using a subdomain resolves it the same way.

***

## Verification states

A domain moves through two independent status fields as it progresses. The dashboard badge reflects both:

| Badge | `verification_status` | `domain_status` | Meaning |
| - | - | - | - |
| Pending Ownership | `0` | `0` | Waiting on the `_firma-verification` TXT record and a `verify-ownership` call |
| Configuring | `1` | `0` | Ownership confirmed, waiting on `finalize` to register with the email provider and issue SPF/DKIM/DMARC records |
| Not Verified | `2` | `0` | Records issued, waiting on DNS propagation and a successful `verify-dns` |
| Verified | `2` | `1` | Fully verified and sending mail |
| Failed | `2` | `2` | Verification failed, or a domain that was previously verified stopped passing checks |
| Domain Conflict | any | any | See [Already using Resend for your own email?](#already-using-resend-for-your-own-email) |

### Stuck in "Configuring"

If a domain sits at `verification_status = 1` for more than a few minutes without progressing, Firma's background job automatically retries the `finalize` call. If it's still stuck after that, the underlying cause is almost always the Resend conflict above - check the domain's `status_message` for `resend_conflict` via `GET /company/domains` before contacting support.

### Verified domain later shows "Failed"

Unlike `verification_status`, `domain_status` **can** move backward from `1` (Verified) to `2` (Failed). Firma periodically re-checks DNS in the background, and if a previously-verified record is later removed or changed - for example, you migrate DNS providers and the CNAME doesn't carry over - the domain flips to Failed. Re-add the missing record(s) and call `verify-dns` again to restore it.

***

## Known display quirk: "pending" after a domain is already verified

Because `verify-dns` re-checks live against the email provider on every call, calling it again on a domain that's already fully verified can occasionally report a transient hiccup even though nothing is actually wrong:

* **In the API**, the top-level `verified` field and `message` string in a `verify-dns` response reflect that specific live check, not the stored record. If the provider has a momentary blip, you can get `"verified": false` with a "not yet verified" message in the same response body where `domain.domain_status` still correctly reads `1` (Verified). **Trust `domain.domain_status`, not the top-level `verified`/`message`, when re-checking an already-verified domain.**
* **In the dashboard**, the status badge at the top of the domain row is authoritative - it's read from the stored record. The "Domain Records" detail dialog shows individual record checks (TXT/CNAME/DMARC) that can occasionally lag behind and show an individual record as still pending even while the overall badge already says Verified. If the two disagree, trust the top-level badge.

If a domain shows Verified in the dashboard, it is sending mail correctly regardless of what a single re-check call reports a moment later.

***

## Related guides

* [White Labeling: Custom email domains](/guides/white-labeling#custom-email-domains) - full API walkthrough, request/response bodies, and workspace-level domain setup
* [Webhooks](/guides/webhooks) - subscribe to `domain.verified` and `domain.verification.failed` events to track ownership verification (Step 2); there is no webhook for the DNS verification step - poll `verify-dns` for that
* [Email Domains API Reference](/api-reference/v01.33.00/email-domains/list-company-domains)


# Databutton
Source: https://docs.firma.dev/guides/databutton-integration

Add legally binding e-signatures to any Databutton app using Python backend functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any Databutton application. Use Databutton's built-in Python backend to call the Firma REST API, manage templates, send signing requests, and track completions via webhooks. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your React UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Databutton](https://databutton.com) account (free trial works for development; paid plans for production)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as a secret

Databutton manages secrets through a dedicated panel in the editor. Values are injected as environment variables into your backend functions at runtime.

1. Open your app in the Databutton editor
2. Click **Secrets** in the sidebar
3. Click **Add Secret**
4. Set the name to `FIRMA_API_KEY` and paste your Firma API key
5. Save

The secret is now available as `os.environ["FIRMA_API_KEY"]` in any backend function.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from backend functions, not from React components directly.

## Step 2: Create a backend function to send signing requests

In Databutton, backend functions are Python FastAPI endpoints. Create a new HTTP API endpoint that calls the Firma `create-and-send` endpoint:

```python theme={null}
# Backend HTTP API endpoint: send_signing_request
import os
import httpx
from fastapi import APIRouter
from fastapi.responses import JSONResponse
from pydantic import BaseModel

router = APIRouter()

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"


class SigningRequestBody(BaseModel):
    template_id: str
    signer_email: str
    signer_first_name: str
    signer_last_name: str


@router.post("/send-signing-request")
async def send_signing_request(body: SigningRequestBody):
    api_key = os.environ.get("FIRMA_API_KEY")
    if not api_key:
        return JSONResponse(content={"error": "FIRMA_API_KEY not configured"}, status_code=500)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{FIRMA_API}/signing-requests/create-and-send",
            headers={
                "Authorization": api_key,
                "Content-Type": "application/json",
            },
            json={
                "name": f"Contract for {body.signer_first_name} {body.signer_last_name}",
                "template_id": body.template_id,
                "recipients": [
                    {
                        "first_name": body.signer_first_name,
                        "last_name": body.signer_last_name,
                        "email": body.signer_email,
                        "designation": "Signer",
                        "order": 1,
                    }
                ],
            },
        )

    data = response.json()

    if response.status_code >= 400:
        return JSONResponse(content={"error": data}, status_code=response.status_code)

    return {
        "signing_request_id": data["id"],
        "first_signer": data.get("first_signer"),
        "status": "sent",
    }
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the backend from your React UI

Databutton apps use React for the frontend. Call your backend endpoint when the user submits the form:

```tsx theme={null}
// pages/SendContract.tsx
import { useState } from "react";

export default function SendContract({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);
  const [result, setResult] = useState<any>(null);

  async function handleSend() {
    setLoading(true);
    try {
      const res = await fetch("/api/send-signing-request", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          template_id: templateId,
          signer_email: "alice@example.com",
          signer_first_name: "Alice",
          signer_last_name: "Johnson",
        }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <button onClick={handleSend} disabled={loading}>
        {loading ? "Sending..." : "Send contract"}
      </button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

You can also ask Databutton's AI chat to wire this up: *"When the user submits the contract form, call the send-signing-request backend endpoint with the template ID, signer email, first name, and last name from the form."* Databutton will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook backend endpoint and register it in the Firma dashboard.

```python theme={null}
# Backend HTTP API endpoint: firma_webhook
from fastapi import APIRouter, Request

router = APIRouter()


@router.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]

        # Update your database, send a notification, or trigger
        # the next step in your workflow
        print(f"Signing request {signing_request_id} completed")

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        print(f"{recipient_email} signed the document")

    return {"received": True}
```

Then register the webhook:

1. Deploy your Databutton app so the endpoint is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```tsx theme={null}
// components/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that Databutton's AI chat can use as context. When connected, the AI references Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Email Deliverability
Source: https://docs.firma.dev/guides/email-deliverability

Understand how Firma sends signing invitation emails, why a recipient can end up on the suppression list, and how to fix a RECIPIENT_EMAIL_SUPPRESSED error.

Firma sends signing invitations, reminders, and other signer-facing emails through [Resend](https://resend.com). This guide explains that delivery path, what causes a recipient to be suppressed, how to read a `RECIPIENT_EMAIL_SUPPRESSED` error, and how to get a wrongly-suppressed address cleared.

***

## A recipient did not receive the signing email

Check the request in this order:

1. Open **Signing Requests**. Confirm that the request is **In Progress**, not **Not Sent**. If it is a draft, open it and select **Send Request**.
2. Before sending a draft, open **Settings** and enable **Send Signing Email**.
3. Select **View details**. Verify the recipient's email address under **Signers**, then ask the recipient to check spam or junk.
4. If Firma.dev reports `RECIPIENT_EMAIL_SUPPRESSED`, follow [Requesting removal](#requesting-removal).
5. For an in-progress request, select **Resend notification to next signer** in the request row. This action sends to the next signer who has not completed their step.
6. To share access directly, under **Signing Links** in the request details, select **Copy Link** for the signer and send the link to them.

When **Send Signing Email** is enabled, test requests send invitation emails too. Their subject starts with `[TEST]`.

## How Firma sends emails

When you send a signing request, Firma builds the email and hands it to Resend for delivery. Resend sends delivery events back to Firma through a webhook - `sent`, `delivered`, `bounced`, `complained`, `opened`, `clicked` - so Firma always knows the last known state of an email it sent.

```
Firma  →  Resend  →  recipient's inbox
  ↑___________________________|
     delivery events (webhook)
```

Firma keeps its own suppression record built from those events, and checks it **before** every send - not just before the first send attempt, but for every signer on a signing request, every time one goes out.

> [!NOTE]
>
> Signing invitations are transactional, not marketing email - recipients don't subscribe to them and can't opt out of a specific signing request. The suppression mechanics on this page exist to stop sending to addresses that can't or won't accept mail, not to manage consent.

## The suppression list, explained

An email address gets suppressed when there's a strong signal it can't or shouldn't receive any more mail from Firma. There are two automatic triggers, plus one manual one:

| Cause | What it means | Suppressed automatically? |
| - | - | - |
| **Hard bounce** | The address is permanently undeliverable - it doesn't exist, the domain is wrong, or the mailbox was closed | Yes, immediately |
| **Spam complaint** | The recipient (or their mail provider) marked the email as spam | Yes, immediately |
| **Soft bounce** | A temporary delivery problem - full mailbox, receiving server briefly unavailable, greylisting | No - Firma logs it but keeps sending |
| **Manually blocked** | Firma support added the address by hand, usually in response to a specific abuse or delivery issue | Yes |

> [!WARNING]
>
> Suppression is per email address and does not clear on its own. Once an address is suppressed, every future signing request to that address will be blocked until the entry is removed - see [Requesting removal](#requesting-removal) below.

Soft bounces are intentionally **not** suppressed: a full mailbox or a momentary server outage usually resolves on its own, and treating every temporary bounce as permanent would suppress addresses that were never actually broken. Only a permanent (hard) bounce or a spam complaint adds an address to the list.

## The RECIPIENT\_EMAIL\_SUPPRESSED error

If you try to send a signing request and any signer's email address is on the suppression list, Firma rejects the entire send before anything goes out:

```json theme={null}
{
  "error": "This signing request couldn't be sent: jane@example.com can't receive email (the address bounced). Please check the address and try again, or contact support if you think this is a mistake.",
  "code": "RECIPIENT_EMAIL_SUPPRESSED"
}
```

* **HTTP status:** `422`
* **Scope:** the check runs against every signer on the request, not just the next one in sequence. A signing request with three signers is rejected up front if signer #3's email is suppressed, even though signers #1 and #2 are fine - this avoids a request getting stuck partway through with credit already spent and some signers already signed.
* **Side effects:** nothing is sent, no credit is deducted, and the signing request is not marked as sent. You can safely fix the address and resend.

The error message names the specific address and the reason phrase: `the address bounced`, `a previous email was marked as spam`, or `the address has been blocked`.

### Diagnosing it

1. Read the address out of the `error` message - that's the recipient that's blocked.
2. Check for a typo in that address. A mistyped domain or a stale address from an old contact list is the most common cause of a hard bounce.
3. If the address is correct and you believe the suppression is wrong (a spam complaint you don't recognize, or a bounce that looks like it should have been transient), continue to [Requesting removal](#requesting-removal).

> [!NOTE]
>
> A signer's email address can't be changed after a signing request has been sent. If a multi-signer request is already stuck because one signer's address got suppressed mid-flow, clearing the suppression won't retroactively fix that request - cancel it and create a new one once the address is cleared.

## Requesting removal

Firma support can review and clear a suppression entry, but there's no self-service way to do it from the dashboard or API today. To request removal:

1. Contact Firma support and provide the exact recipient email address and, if you have it, the signing request ID that hit the error.
2. Support checks the suppression reason against the underlying Resend delivery record for that address.
3. If the suppression was caused by a transient issue misclassified as permanent, or the complaint doesn't hold up, support removes the entry.

Repeated tickets about the same address usually mean the underlying cause hasn't been fixed - for example, resending to a hard-bounced address without first checking whether it's still valid will get it suppressed again after the next hard bounce.

## Preventing re-suppression

* **Verify addresses before sending.** A typo'd domain or a stale address from an imported contact list is the single most common cause of a hard bounce.
* **Avoid role-based or shared inboxes** like `info@`, `noreply@`, or `admin@` for signer addresses. Nobody owns them individually, so they're more likely to auto-filter incoming mail to spam (generating a complaint) or to be turned off entirely (generating a hard bounce).
* **Watch for a pattern across signing requests.** If several signers at the same company domain bounce, it's more likely a company-wide mail server change than several unrelated typos - worth confirming with the customer before resending.
* **Send from a custom domain.** Firma's shared sending domain carries the combined sending reputation of every customer using it. A [verified custom domain](/guides/custom-domains) isolates your reputation, which reduces the odds of a hard bounce or spam classification caused by someone else's sending behavior.

## Next steps

* [Custom Domains](/guides/custom-domains) - set up your own sending domain for better deliverability and branding
* [Webhooks](/guides/webhooks) - subscribe to `signing_request.recipient.signed` and `signing_request.recipient.declined` events to track signing progress
* [Sending a Signing Request](/guides/sending-signing-request) - creating and sending signing requests via the API


# Embeddable signing
Source: https://docs.firma.dev/guides/embeddable-signing

Embed the signing experience into your product so signers can complete documents without leaving your app.

# Embeddable signing

Embed the signing flow directly in your application so recipients can sign documents without leaving your product. This creates a seamless, white-label signing experience.

## Signing URL pattern

The signing interface is available at:

`https://app.firma.dev/signing/{signing_request_user_id}`

## URL parameters

The signing URL accepts optional query parameters to customize the experience:

| Parameter | Type | Range | Default | Description |
| - | - | - | - | - |
| `lang` | string | `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca` | Browser language | Override UI language |
| `zoom` | float | `0.25`–`3.0` | fit-to-width | Initial zoom level (`1.0` = 100% natural size) |

Example with both parameters:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=fr&zoom=1.0
```

Without `zoom`, the signing view automatically fits the PDF to the container width. On wide screens this can produce 150–200% zoom. Set `zoom=1.0` for natural reading size, or a lower value like `zoom=0.75` for a more compact view.

## Basic iframe embed

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

### Required iframe permissions

* `camera` - For identity verification (if enabled)
* `microphone` - For video verification (if enabled)
* `clipboard-write` - For copying/pasting content

## Getting the signing URL

The `signing_request_user_id` is returned when you fetch signing request users via the API.

### Example: Get recipient signing URLs

```js theme={null}
const response = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}/users`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
)

const users = await response.json()

// Each user has their own signing URL
users.forEach(user => {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  console.log(`${user.email}: ${signingUrl}`)
})
```

## Complete implementation example

### React component

```jsx theme={null}
import { useState, useEffect } from 'react'

function SigningView({ signingRequestId, recipientEmail }) {
  const [signingUrl, setSigningUrl] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
  
  useEffect(() => {
    async function loadSigningUrl() {
      try {
        // Fetch signing request users from your backend
        const response = await fetch(
          `/api/signing-requests/${signingRequestId}/users`,
          { credentials: 'include' }
        )
        
        if (!response.ok) {
          throw new Error('Failed to load signing users')
        }
        
        const users = await response.json()
        
        // Find user by email
        const user = users.find(
          u => u.email === recipientEmail
        )
        
        if (!user) {
          throw new Error('User not found')
        }
        
        const url = `https://app.firma.dev/signing/${user.id}`
        setSigningUrl(url)
        setLoading(false)
      } catch (err) {
        setError(err.message)
        setLoading(false)
      }
    }
    
    loadSigningUrl()
  }, [signingRequestId, recipientEmail])
  
  if (loading) return <div>Loading signing interface...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <iframe
      src={signingUrl}
      style={{
        width: '100%',
        height: '900px',
        border: 0
      }}
      allow="camera;microphone;clipboard-write"
      title="Sign Document"
    />
  )
}
```

### Server-side endpoint (Node.js)

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/signing-requests/:id/users', async (req, res) => {
  try {
    const response = await fetch(
      `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${req.params.id}/users`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const users = await response.json()
    res.json(users)
  } catch (error) {
    console.error('Failed to fetch signing users:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
})

app.listen(3000)
```

## postMessage events

The signing iframe emits postMessage events for tracking signing progress:

```js theme={null}
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://app.firma.dev') return
  
  const data = event.data
  
  switch (data.type) {
    case 'signing.started':
      console.log('User started signing')
      break
    case 'signing.completed':
      console.log('Document signed successfully')
      // Redirect or show success message
      break
    case 'signing.declined':
      console.log('User declined to sign')
      break
    case 'signing.error':
      console.error('Signing error:', data.error)
      break
  }
})
```

A second embedded tab or device that opens or reloads the signing link after the signer has finished receives no `signing.completed` or `signing.error` message: that tab shows the already-signed screen. A tab that was already open before the signer finished can still send `signing.completed` (on Finish) or `signing.error` (on Decline). The `signing_request.recipient.signed` and `signing_request.completed` webhooks remain the host's durable signals.

## Security best practices

> [!WARNING]
>
> **Never expose API keys in frontend code.** Always fetch signing user IDs through a secure backend endpoint.

### ✅ Do's

* ✅ Fetch signing user IDs through your backend
* ✅ Validate postMessage origins (`https://app.firma.dev`)
* ✅ Use HTTPS for all API requests
* ✅ Monitor signing events via webhooks (60 req/min)

### ❌ Don'ts

* ❌ Don't expose API keys in client code
* ❌ Don't trust postMessage data without origin validation

## Rate Limits

See the guide on [Rate Limits](/guides/rate-limits).

## Webhook integration

Use webhooks to track signing events in real-time instead of polling:

```js theme={null}
// Webhook handler
app.post('/webhooks/firma', async (req, res) => {
  const event = req.body
  
  switch (event.event_type) {
    case 'signing_request.viewed':
      await notifyUser(event.data.signing_request_id, 'viewed')
      break
    case 'signing_request.recipient.signed':
      await notifyUser(event.data.signing_request_id, 'signed')
      break
    case 'signing_request.completed':
      await markComplete(event.data.signing_request_id)
      break
  }
  
  res.json({ received: true })
})
```

See the [Webhooks guide](/guides/webhooks) for complete implementation details.

## Troubleshooting

If the signing page is blank or black, ask the signer to reload it, try a private window or another supported browser, disable content blockers for the page, and confirm that hardware acceleration is enabled.

### Iframe not loading

**Possible causes**:

* Invalid `signing_request_user_id`
* Recipient already completed signing
* Signing request was cancelled or expired

**Solution**: Verify signing request status via API

### postMessage events not received

**Possible causes**:

* Origin validation blocking messages
* Event listener not attached before iframe loads

**Solution**:

* Check origin is exactly `https://app.firma.dev`
* Attach listener before creating iframe

### 403 Forbidden when fetching signing request

**Possible causes**:

* User doesn't have access to the signing request
* API key lacks required permissions

**Solution**: Verify authorization logic and API key permissions

## Next steps

* [Send signing requests](/guides/sending-signing-request) with custom templates
* [Set up webhooks](/guides/webhooks) for real-time event notifications (60 req/min)
* [Workspace settings](/guides/workspace-settings) for customizing email branding (100-200 req/min)


# Embeddable signing request editor
Source: https://docs.firma.dev/guides/embeddable-signing-request-editor

Embed the signing request editor in your product with secure JWT authentication.

# Embeddable signing request editor

Embed Firma's signing request editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label signing workflows**: Manage signing requests under your brand
* **Multi-tenant applications**: Secure per-signer access without exposing API keys
* **Embedded document workflows**: Seamless signing request management within your product
* **Time-limited access**: Tokens expire automatically for security (7-day expiration)

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the signing request ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 7 days

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific signing request using the `/jwt/generate-signing-request` endpoint.

**Endpoint**: `POST /jwt/generate-signing-request`

**Request body**:

```json theme={null}
{
  "companies_workspaces_signing_requests_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (200 OK)**:

```json theme={null}
{
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "jwt_id": "jwt123-e89b-12d3-a456-426614174000",
  "expires_at": "2024-04-27T10:00:00Z",
  "signing_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-04-20T10:00:00Z"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a signing request ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateSigningRequestToken(signingRequestId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_signing_requests_id: signingRequestId
    })
  })
  
  const data = await response.json()
  return data.jwt
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_signing_request_token(signing_request_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/jwt/generate-signing-request',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_signing_requests_id': signing_request_id
        }
    )
    data = response.json()
    return data['jwt']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Signing Request Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>

<!-- Create a container for the editor -->
<div id="signing-request-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const signingRequestId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the signing request editor
  const editor = new FirmaSigningRequestEditor({
    container: '#signing-request-editor-container',
    jwt: jwt,
    signingRequestId: signingRequestId,
    showCloseButton: true, // Show close button in header
    onSave: (data) => {
      console.log('Signing request saved:', data);
    },
    onSend: (data) => {
      console.log('Signing request sent:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (signingRequest) => {
      console.log('Editor loaded successfully:', signingRequest);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function SigningRequestEditorComponent({ signingRequestId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Signing Request Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaSigningRequestEditor({
      container: containerRef.current,
      jwt: jwt,
      signingRequestId: signingRequestId,
      showCloseButton: true, // Show close button in header
      onSave: (data) => console.log('Saved:', data),
      onSend: (data) => console.log('Sent:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (signingRequest) => console.log('Loaded:', signingRequest)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, signingRequestId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default SigningRequestEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement | DOM element to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `signingRequestId` | string | Signing request identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `onSave` | function | Callback when signing request is saved |
| `onSend` | function | Callback when signing request is sent |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with signing request data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's signing request editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and sends.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "signing_request.saved", // or signing_request.sent, signing_request.closed
	"payload": {
		"signing_request_id": "sr_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"status": "draft" // or "sent"
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'signing_request.saved':
			console.log('Signing request saved', data.payload)
			// Optionally fetch the latest signing request via API
			break
		case 'signing_request.sent':
			console.log('Signing request sent', data.payload)
			// Trigger webhook or notification
			break
		case 'signing_request.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with a 7-day expiration time for typical editing workflows. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically after 7 days based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* A new token must be requested to continue
* No API call needed — tokens expire passively

### Token refresh (optional)

For long-running editing sessions, you can refresh the token before expiration using the `updateJWT()` method:

```js theme={null}
// Generate a new JWT from your backend
const newJwt = await fetch('/your-backend/generate-token').then(r => r.json());

// Update the editor with the new token
editor.updateJWT(newJwt.jwt);
```

***

## Rate limiting

JWT endpoints support **120 requests per minute per API key**.

**Rate limit headers**:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1729180800
```

If you exceed the rate limit (429 response):

* Cache tokens and reuse them until expiration (7 days)
* Implement exponential backoff for retries
* Monitor `X-RateLimit-Remaining` header
* Generate tokens on-demand, not preemptively

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits (120 requests/minute)
* ✅ Use HTTPS for all API requests
* ✅ Use `readOnly: true` for view-only access

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across sessions or signers
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different signing requests

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration (7-day window)
* Generate a new token and call `editor.updateJWT(newToken)`
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Signing request not found when generating JWT

**Possible causes**:

* Signing request ID doesn't exist
* Signing request belongs to different workspace
* Signing request was deleted

**Solution**: Verify signing request ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching (7-day expiration window is generous)
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with exponential backoff

### Editor not loading

**Symptom**: Container is empty or shows loading spinner indefinitely

**Possible causes**:

* Script not loaded (check `script.onload` event)
* Invalid JWT or signing request ID
* CORS issues (check browser console)

**Solution**:

* Verify the script is loaded from `https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js`
* Check JWT is valid and not expired
* Ensure backend returns correct CORS headers

***

## Next steps

* [Embed template editor](/guides/embeddable-template-editor) for white-label template creation (120 req/min)
* [Send signing requests](/guides/sending-signing-request) programmatically (100 req/min)
* [Set up webhooks](/guides/webhooks) to track signing request events (60 req/min)
* [Configure workspace settings](/guides/workspace-settings) for multi-tenant apps (100-200 req/min)


# Embeddable template editor
Source: https://docs.firma.dev/guides/embeddable-template-editor

Embed the template editor in your product with secure JWT authentication.

Embed Firma's template editor inside your application using JWT authentication for secure, time-limited access. This is ideal for white-label integrations and multi-tenant applications.

## Use cases

* **White-label template editing**: Let users edit templates under your brand
* **Multi-tenant applications**: Secure per-user template access without exposing API keys
* **Embedded workflows**: Seamless template creation within your product
* **Time-limited access**: Tokens expire automatically for security

## How it works

1. Your server requests a JWT token from Firma's API using your API key
2. Firma returns a short-lived JWT token with the template ID
3. Your frontend embeds the editor with the JWT token
4. The token expires automatically after 24 hours

> [!NOTE]
>
> **Rate limit**: JWT endpoints support **120 requests per minute per API key** for high-volume applications.

***

## JWT Authentication

### Generate JWT token

Generate a JWT token for a specific template using the `/generate-template-token` endpoint.

**Endpoint**: `POST /generate-template-token`

**Request body**:

```json theme={null}
{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

**Response (201 Created)**:

```json theme={null}
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}
```

**Rate limit headers**:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800
```

***

## Implementation guide

> [!WARNING]
>
> **Security**: Never expose your API key in client-side code. Always generate JWT tokens from your secure backend.

### Backend: Generate JWT token

Call the Firma API from your backend to generate a JWT token. Your backend endpoint should accept a template ID and return the JWT to your frontend.

**Node.js example**:

```js theme={null}
// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}
```

**Python example**:

```py theme={null}
import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']
```

### Frontend implementation — HTML / Vanilla JavaScript

```html theme={null}
<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>
```

### Frontend implementation — React

```jsx theme={null}
import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;
```

### Configuration Options

| Option | Type | Description |
| - | - | - |
| `container` | HTMLElement \| string | DOM element or CSS selector to mount the editor (required) |
| `jwt` | string | Authentication token from your backend (required) |
| `templateId` | string | Template identifier (required) |
| `theme` | `'dark'` \| `'light'` | Editor theme (default: `'dark'`) |
| `readOnly` | boolean | Enable read-only mode (default: `false`) |
| `height` | string | Container height (default: `'100vh'`) |
| `width` | string | Container width (default: `'100%'`) |
| `showCloseButton` | boolean | Show a close button in the editor header (default: `false`) |
| `autoFit` | boolean | Fit the document to the container initially (default: `true`) |
| `initialZoom` | number | Set the initial zoom; takes precedence over `autoFit` |
| `onSave` | function | Callback when template is saved |
| `onClose` | function | Callback when close button is clicked or `triggerClose()` is called. Receives `{ hasUnsavedChanges: boolean }` |
| `onError` | function | Callback for error handling |
| `onLoad` | function | Callback when editor loads with template data |

### Instance Methods

| Method | Description |
| - | - |
| `triggerClose()` | Programmatically triggers the close flow. Checks for unsaved changes and invokes `onClose` with `{ hasUnsavedChanges: boolean }` |

Use `triggerClose()` when your host application needs to close the editor from its own UI — for example, a parent navigation event or a "back" button:

```js theme={null}
// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});
```

## postMessage events (editor → host)

Firma's editor will emit postMessage events for important lifecycle actions. Below is a recommended, minimal event schema you can implement for reacting to editor saves and publishes. If you have a canonical schema in your platform, replace these with your official event names.

> [!TIP]
>
> Use these events to track editor activity without making additional API calls, helping you stay within rate limits.

Event envelope (window\.postMessage payload):

```json theme={null}
{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}
```

### Client listener example (plain JS)

```js theme={null}
window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})
```

***

## Token lifecycle management

JWT tokens are generated with sufficient expiration time for typical editing sessions. The editor will automatically handle token expiration.

### Automatic expiration

JWT tokens expire automatically based on the `expires_at` timestamp. After expiration:

* The embedded editor will reject the token
* Users must request a new token to continue
* No API call needed — tokens expire passively

***

## Rate limiting

See the guide on [Rate Limits](/guides/rate-limits).

***

## Security best practices

> [!WARNING]
>
> **Never expose your API key in client-side code.** Always generate JWT tokens from a secure server endpoint.

### ✅ Do's

* ✅ Generate tokens from your backend server
* ✅ Monitor rate limits
* ✅ Use HTTPS for all API requests

### ❌ Don'ts

* ❌ Don't expose API keys in frontend code
* ❌ Don't reuse tokens across users
* ❌ Don't log JWT tokens (security risk)
* ❌ Don't share tokens between different templates

***

## Troubleshooting

### Token expired error

**Symptom**: Editor shows "Token expired" or authentication error

**Solution**:

* Implement token refresh before expiration
* Generate a new token and reload the iframe
* Check system clock synchronization

### 401 Unauthorized

**Symptom**: JWT generation fails with 401

**Possible causes**:

* Invalid or missing API key
* API key doesn't have required permissions
* API key is disabled

**Solution**: Verify API key in dashboard and check permissions

### 404 Not Found

**Symptom**: Template not found when generating JWT

**Possible causes**:

* Template ID doesn't exist
* Template belongs to different workspace
* Template was deleted

**Solution**: Verify template ID and workspace access

### Rate limit exceeded

**Symptom**: 429 Too Many Requests

**Solution**:

* Implement token caching
* Increase token expiration time
* Wait for rate limit reset (check `X-RateLimit-Reset` header)
* Implement retry logic with backoff

***

## Next steps

* [Embed signing interface](/guides/embeddable-signing) for white-label signing (100 req/min)
* [Send signing requests](/guides/sending-signing-request) with custom templates (100 req/min)
* [Set up webhooks](/guides/webhooks) to track template events (60 req/min)


# FAQ
Source: https://docs.firma.dev/guides/faq

Answers to the questions Firma.dev support receives most often, with links to the guide that covers each topic in depth.

## Getting started & account

> **Where do I find my live/test API keys, and can I get them via API?**
>
> Yes. Your account's main key is on the dashboard's **Dashboard** page; each workspace's own keys are on that workspace's **Info** tab, and there's no separate "Settings > API Keys" page. You can also fetch them via the API. Only the workspace **Owner** can generate or regenerate keys from the dashboard.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#create-your-account-get-your-api-key)

> **Is there a free trial or sandbox? What does test mode cost?**
>
> No, Firma.dev doesn't offer a separate trial period or sandbox account, and test mode doesn't cost anything to use. Test-key requests are still subject to the normal API rate limits, same as live requests, and the embeddable editors and hosted signing page behave identically in test mode and live mode.
>
> **See:** [API Authentication & JWT Tokens](/guides/authentication#test-mode-live-vs-test-keys), [Complete Setup Guide](/guides/complete-setup-guide#start-in-test-mode)

> **Do I need to sign a contract or book a demo before using Firma.dev?**
>
> No. Signing up is self-serve, with no contract and no sales demo required: create an account, accept the standard terms of service at signup, and get your API key from the dashboard. Pricing has no minimums, no contracts, and no monthly fees. You can integrate directly from the docs, the MCP server, or one of Firma.dev's AI-coding-tool integration guides (Claude Code, Cursor, ChatGPT, and others) without ever talking to sales.

> **What is the difference between the Owner, Admin, and View Only roles?**
>
> Firma.dev has three account roles: **Owner**, **Admin**, and **View Only**.
>
> * **Owner**: the only role that can manage billing, create, delete, or rename workspaces, and generate or regenerate API keys.
> * **Owner and Admin**: can both manage webhooks, custom domains, company settings, users, and signing requests. Workspace settings stored on the workspace, such as OTP verification, terms acceptance, and the signature frame, can be changed only by an Owner.
> * **View Only**: can only read and copy existing data.
>
> A few workspace toggle settings, like OTP verification or the signature frame display, are Owner-only on the backend. The UI doesn't yet block Admin or View Only users from toggling them, so a non-Owner may see a "saved" confirmation even though the change didn't apply. If a setting doesn't seem to stick, have an Owner make the change.

> **How do I add a team member?**
>
> Owners and Admins can add people to your company:
>
> 1. Open **Users** in the sidebar and click **Add User**.
> 2. Enter their name and email address, and choose an **Account Level**: **Admin** or **View Only** (only an Owner can add another **Owner**). The roles question above explains what each level can do.
> 3. Click **Send Invitation**.
>
> If the email address has no Firma.dev account yet, the account is created right away and a temporary password is shown once on screen. No invitation email is sent, so share that password with them (see the next question). If the person already has a Firma.dev account, they are added to your company immediately and keep their existing password.

> **Why didn't a new team member receive an invitation email?**
>
> By design, adding a team member creates their account immediately instead of sending an email invitation: the new user's temporary password is shown once on screen at creation time, not emailed. Share that password with them so they can log in, then they'll be prompted to set their own password on first login. If the temporary password is lost before it's used, use **Forgot password** on the login page to reset it.

> **How do I change my account email, or merge/delete an account?**
>
> Change your **login email** from the **My Profile** dialog (open it from your avatar or "My Profile" in the sidebar); this triggers a standard email-change confirmation flow to the new address. The Account page's Company Information tab also has an "Email" field, but that's a separate company-level billing/notification contact address: changing it does not affect how you log in. Signing up with a different email always creates a separate account; Firma.dev has no self-serve way to merge accounts. To merge accounts or delete your account entirely, contact support.

> **Why is my password reset link expired, or the email missing?**
>
> Password reset links are single-use and time-limited; once a link has been opened once (or opened automatically on your behalf), a second click shows as expired or invalid, and you'll need to request a fresh one from **Forgot password**. A common cause of a link being consumed before you click it is a corporate email security scanner that automatically opens links in incoming mail; a shared or alias mailbox can also delay or filter the message. Make sure you're requesting the reset for the exact email address your account is registered under, and contact support if the problem continues.

> **How does integration with Firma.dev work?**
>
> You integrate through Firma.dev's REST API, optionally paired with its embeddable editors. Firma.dev also provides a TypeScript SDK, and publishes step-by-step guides for platforms such as n8n, Supabase, and Lovable, beyond the AI coding-tool clients its MCP servers cover.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide), [Embeddable signing](/guides/embeddable-signing), [MCP Integration](/guides/mcp)

> **What can I do with the Firma.dev API?**
>
> The API covers the full e-signature workflow, from creating a signing request to receiving a signed, sealed document. Fields can also be placed with anchor tags, with conditional and required-field rules, email OTP verification, and full control over every email Firma.dev sends. Completed documents are sealed as PAdES-B-LTA PDFs with a completion certificate, and each workspace isolates a customer's branding, sending domains, and email templates.
>
> **See:** [Sending a signing request](/guides/sending-signing-request), [Webhooks](/guides/webhooks), [Audit Trail](/guides/audit-trail)

> **How do I contact Firma.dev support? Is there a support email?**
>
> Use the built-in Help: open **Help** in the sidebar and ask your question. If the answer doesn't solve it, click **This didn't answer my question** under the answer to submit a support ticket. The ticket includes your conversation, so you don't need to repeat it.

## Pricing & billing

> **What does one credit cover, and when is it charged or refunded?**
>
> One credit covers a single signing request, charged when you send it and never refunded afterward. One credit equals one signing request (envelope), regardless of how many signers or documents it contains. It's deducted when the request is sent, right after the signing emails go out and before the request is marked sent, not when signers finish. Credits aren't refunded if a signer declines or the request expires, and no credit is charged if send validation fails or the email itself fails to send.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **How much does Firma.dev cost, and are there subscriptions or minimums?**
>
> Firma.dev is pay-as-you-go, with no subscriptions, minimums, or seat fees. Credits don't expire. Accounts created before Firma.dev's most recent price change, or signed up through another customer's referral code, keep that earlier, lower per-credit rate for the life of the account. A referral code doesn't gate access (anyone can sign up freely), but it earns both parties bonus credits on the referred company's first purchase.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

> **Where do I enter an AppSumo, promo, or referral code?**
>
> * When you create your account, select **Have a promo or referral code?**, then enter the AppSumo or other promo code in **Promo Code** before you sign up.
> * To apply a code later, go to **Account > Credits & Billing**, choose a credit bundle, select **Have a promo or referral code?**, enter it in **Promo / Referral Code**, select **Apply**, and complete the purchase.
>
> The bonus depends on the promo code. Some codes add configured bonus credits at registration. A code can also add a flat or percentage bonus with a credit purchase. For referral code benefits, see [the pricing and referral code answer](#how-much-does-firma-dev-cost-and-are-there-subscriptions-or-minimums).

> **Where do I download invoices, and how do I add my company name and VAT number?**
>
> Download invoices from **Account > Credits & Billing**, and add your company details before checkout. Enter your company name, billing address, and VAT number in the **Add tax number** step of the Paddle checkout before you pay. To correct an already-issued invoice, contact support through **Help** in the dashboard sidebar with the invoice number, company name, billing address, and VAT ID. It's reissued and shown via the same View link.
>
> **See:** [Platform Updates: Invoice downloads](/guides/platform-updates#invoice-downloads)

> **Why does adding credits fail with a Paddle.js error?**
>
> This is almost always caused by an ad blocker, privacy extension, or corporate network filter blocking Paddle's checkout script from loading. Firma.dev surfaces this as "Failed to load payment system: Failed to load Paddle.js." Try disabling the blocker for the site, or open the page in a private/incognito window or a different browser. If a purchase seems to have failed partway through, check **Account > Credits & Billing > Transaction History** to confirm whether it actually went through before retrying, so you don't pay twice.

> **How do I handle high volume, and is there auto-recharge?**
>
> Yes, auto-recharge is available. Buy credits any time from **Account > Credits & Billing**, and turn on **Auto-Recharge** in that same tab to automatically purchase a set credit bundle whenever your balance drops below a threshold you choose. There are no volume-based discount tiers currently; every credit bundle is priced at your account's standard per-credit rate regardless of how much you buy at once.
>
> **See:** [Complete Setup Guide](/guides/complete-setup-guide#monitor-usage-check-credits)

## Sending signing requests

> **Why weren't any emails sent after I created a signing request via the API?**
>
> `POST /signing-requests` only creates a draft. It never sends an email on its own, regardless of your `settings`.
>
> **See:** [Sending a signing request: Create vs. create-and-send](/guides/sending-signing-request#create-vs-create-and-send)

> **Can I send signing links through my own email system instead of Firma.dev's?**
>
> Yes, you can suppress Firma.dev's own signing and completion emails and send the signing link through your own system instead.
>
> * `settings.send_signing_email: false`: suppresses Firma.dev's notification email while the request still sends, and it works whether you call `/send` or `create-and-send`.
> * `settings.send_finish_email: false`: turns off the completion email the same way.
> * `reminders`: array you provide on create that controls reminder emails, with document-based requests getting none by default and template-based requests inheriting the template's reminders unless you override it.
>
> **See:** [Sending a signing request: The send\_signing\_email flag](/guides/sending-signing-request#the-send_signing_email-flag) and [Sending a signing request: Embedding the signing view](/guides/sending-signing-request#embedding-the-signing-view)

> **What's the correct API base URL, and why do documented paths 404?**
>
> The correct base URL is:
>
> ```text theme={null}
> https://api.firma.dev/functions/v1/signing-request-api
> ```
>
> Append the resource path after it, e.g. `.../signing-requests`. 404s often come from two sources:
>
> * `https://api.firma.dev/api/v1`: a second, "Planned" server listed in the public OpenAPI spec for a future API shape, not a real endpoint, so a generated client pointed at it 404s on every call.
> * `POST /signing-requests`: the actual endpoint behind the "Create Signing Request" reference page, not a `/create-signing-request` route as the title might suggest.
>
> **See:** [Authentication: Code Examples](/guides/authentication#code-examples)

> **What does a valid create-signing-request payload look like (recipients, fields, positions)?**
>
> A valid payload has a `recipients` list and a `fields` list; each field points at a recipient and a position on the page.
>
> Each recipient needs `first_name` and `email`. `designation` is optional and defaults to `Signer`; you can also set it to `Approver` or `CC`. `last_name` is required when you create from a raw `document` or `document_id` with `POST /signing-requests`, and optional for template-based requests. `order` is optional.
>
> Each field needs:
>
> * `type`: one of the supported field types, which also include `radio_buttons`, `text_area`, `url`, `file`, and `stamp`.
> * `page_number`: the page the field appears on.
> * `position`: `x`, `y`, `width`, `height` as percentages of the page, not pixels.
> * `recipient_id`: the recipient the field belongs to.
>
> To reference a recipient you haven't created yet, give it a temporary `id` starting with `temp_` (for example `temp_alice`) and set `recipient_id` on the field to the same value. The API maps it to a real UUID and never returns temp IDs.
>
> There's no top-level `metadata` property. Use each recipient's `custom_fields` object instead.
>
> **See:** [Sending a signing request: Recipient Schema](/guides/sending-signing-request#recipient-schema-required-fields) and [Sending a signing request: Field types](/guides/sending-signing-request#field-types)

> **What's the maximum document size, and how do I upload large files?**
>
> The maximum document size is 50MB (52,428,800 bytes). Upload large files with the two-step process:
>
> * `POST /documents`: uploads the file and returns a presigned `upload_url`.
> * `PUT`: send the file to that `upload_url`.
> * `document_id`: pass this when you create the signing request.
>
> Keep inline base64 in `document` under about 5 MB. A request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. Before October 13, 2026, the gateway returned `502`. The MCP server has no upload tool, so large files go through the REST API.

> **Does Firma.dev support DOCX, and why does DOCX conversion sometimes fail?**
>
> Yes, Firma.dev supports DOCX and converts it to PDF automatically on the server before the signing request is created.
>
> * `POST /signing-requests`: accepts a DOCX file when you create a signing request directly.
> * `POST /documents`: accepts a DOCX file when you upload a document separately.
>
> That converter only renders text, headings, lists, and tables. It drops any images in the DOCX entirely, and it only loads a Latin/Cyrillic-style font set, so text in right-to-left scripts like Hebrew or Arabic can come out with missing glyphs or misrendered.
>
> If your document has images or non-Latin script you need preserved exactly, export it to PDF yourself first (e.g. LibreOffice, or Google Docs > File > Download > PDF) and send the PDF instead of the DOCX.

> **Why do I get duplicate signing requests, and is there an idempotency key?**
>
> No. The write endpoints (`create`, `create-and-send`, `send`, `resend`) have no `Idempotency-Key` header.
>
> An auto-retried `create` or `create-and-send` call can create a duplicate, separately billed, legally binding signing request. Calling `/send` again on an already-sent request returns an error instead of duplicating.
>
> To avoid duplicates, store the `id` returned by the first call and check for it, or query existing requests, before retrying.
>
> **See:** [n8n integration: Other common operations](/guides/n8n-integration#other-common-operations)

> **Can I change a recipient's email after sending, or cancel silently?**
>
> No, you can't edit a recipient's email after sending. Cancel and recreate the request instead.
>
> You can cancel silently:
>
> * `POST /signing-requests/{id}/cancel`: the endpoint to call to cancel a request.
> * `notify_signers: false`: a parameter on that cancel call itself, not a creation-time setting, that suppresses the signer notification.
> * `settings.send_cancellation_email` on the signing request (default `true`) must also be true for a cancellation email to be sent.
>
> **See:** [Signing patterns: Error handling: 409 ALREADY\_SENT](/guides/signing-patterns#error-handling-409-alreadysent)

> **Can a signing request include multiple documents, or swap a template's document?**
>
> Yes. Since October 13, 2026, a template or signing request can hold up to 20 documents (100 MB per set). Upload each file with `POST /documents`, then send the ids in document order as `document_ids` on `POST /templates`, `POST /signing-requests` or `POST /signing-requests/create-and-send`. Send exactly one document source: `document`, `document_id`, `document_ids` or `template_id`.
>
> Use the `/documents` routes on a template or a draft signing request to add, replace, rename, reorder and remove each document; once a signing request is sent, finished, cancelled or declined, these changes answer `409 DOCUMENT_SET_LOCKED`. Download each document of a signing request with `GET /signing-requests/{id}/documents/{document_id}/download`, as uploaded or individually sealed.
>
> To swap one document and keep its fields, replace it with `PATCH .../documents/{document_id}` and a new upload with the same page count and page sizes (within 1 pt); on a signing request, a document placed with anchor tags is replaced only when the new upload's anchors resolve exactly as stored. See the [API changelog v1.39.0](/guides/api-changelog#v1390).

> **How do I download the signed PDF and certificate via the API?**
>
> `GET /signing-requests/{id}/download` returns the signed PDF as a pre-signed URL.
>
> It returns a single, short-lived pre-signed `download_url`, valid until the `expires_at` timestamp: the final PDF for a finished request, or a partial-progress snapshot for a sent request that isn't finished. For a finished request, that one PDF already has the completion certificate and audit-trail pages appended to the signed document, and there's no separate certificate-only download URL from this endpoint. To get separate files when they exist, read `document_only_download_url` and `certificate_only_download_url` from `GET /signing-requests/{id}`.
>
> Calling this endpoint behaves differently depending on the signing request's state:
>
> * `409`: returned if you call it before the request has been sent, or for a finished request while its completion certificate is still being generated.
> * For a sent request that isn't finished (in progress, expired, cancelled or declined): returns a partial-progress snapshot of the signers who have completed so far. There's no setting to turn this on.
> * `503`: returned with a `Retry-After` header while a partial-progress snapshot is still being generated.

> **Can I retrieve a signer's signature image or uploaded files via the API?**
>
> Yes, you can retrieve a signer's signature image and any files they uploaded through the API.
>
> * `GET /signing-requests/{id}/signers/{signer_id}/signature`: returns the adopted signature as a `data:image/png;base64,...` data URI.
> * `GET /signing-requests/{id}/signers/{signer_id}/initials`: returns the adopted initials the same way.
> * `GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}`: returns a stamp image for the given `field_id`, since stamps are per-field.
> * `GET /signing-requests/{id}/signers/{signer_id}/files/{field_id}`: returns a pre-signed download URL, valid for 300 seconds, for a file uploaded to a `file`-type field, not the file bytes directly.
> * `GET /signing-requests/{id}/fields`: filter to `type=file` to find the `field_id` for an uploaded file.
>
> Uploaded files are never embedded into the final signed PDF or certificate; they only exist as retrievable attachments through these endpoints.

> **How do I read field values back by variable name after signing?**
>
> `GET /signing-requests/{id}/fields` returns every field of the request; read each entry's `value` property for the resolved value and match on `variable_name`.
>
> **See:** [Field Prefilling: Reading field values back](/guides/field-prefilling#reading-field-values-back)

## Templates / fields / anchor tags

> **How are field x/y/width/height interpreted?**
>
> `x`, `y`, `width`, and `height` are percentages of the page, not pixels. The origin is the top-left corner and `y` grows downward.
>
> A manually specified field returns a `400` error when `x+width>100` or `y+height>100`. Fields placed by anchor tags are clamped back onto the page instead.

> **How do anchor tags work, and which field types do they support?**
>
> Place literal marker text in the document and pass an `anchor_tags` array on a document-based create request, up to 100 tags per request.
>
> Anchor tags accept every field type, and also `dropdown_options`, `format_rules`, `multi_group_id`, and `conditions`.

> **Why isn't anchor text removed, or why does the field look offset?**
>
> `remove_anchor_text` makes the matched text invisible in the PDF's content stream rather than deleted.
>
> It can fail on embedded/subset (CID) fonts or when the marker text is split across separate PDF text-show operators. When that happens, the system automatically draws a white box over only the matched marker area, even without `add_white_background` set.

> **What does 'no glyph advances for font' mean?**
>
> This error means the anchor marker's text sat inside a PDF Form XObject or transparency group that was not replayed when reading glyph positions.
>
> This typically happens in HTML-to-PDF documents, where a Chromium print pipeline wraps an element with CSS `opacity` below 1, or a `transform`, inside a transparency-group Form XObject.
>
> The extractor replays text inside form and group contexts (annotation appearance streams excluded), so anchors placed there are found.
>
> If it recurs, the anchor is likely in a malformed or unusual font/geometry construct. Re-export the source PDF with standard font encoding.

> **How do I prefill fields, and can the signer still edit the value?**
>
> Set `format_rules.prefilledData` on a field to auto-fill and lock it from recipient data.
>
> The signer can still edit the value if you also set `format_rules.prefilledEditable` to `true`.
>
> This works the same way on anchor-tag-placed fields, since anchor tags accept `format_rules` too.

> **Why does field text shrink or get cut off, and can I set a font size?**
>
> Text fields automatically shrink to fit the field's box when a value overflows, down to a default floor of 8px.
>
> Set `format_rules.fontSize` for an explicit starting size instead. If text is still cut off, enlarge the field or switch to a `textarea`.

> **How do I build single-select checkbox groups, and why do radio/checkbox values show as true/false?**
>
> Assign the same `multi_group_id` to a set of fields to link them into a group.
>
> * `radio_buttons`: fields sharing a `multi_group_id` form a mutually-exclusive group.
> * `checkbox`: fields sharing a `multi_group_id` form an independent group.
>
> A selected radio option's stored value is the literal string `"true"`.
>
> A `checkbox` field renders as a native checkbox input, not a custom checkmark icon.

> **How do conditional visibility/required rules work via the API, and why weren't they applied?**
>
> `visibility_conditions` and `required_conditions` are `ConditionSet` objects on a field that reference another field's `field_id` on the same recipient.
>
> * `GET /templates/{id}/fields`: returns both properties, even though the public OpenAPI schema omits them.
>
> When you create a signing request from a template (two-step flow, create-and-send, or `/duplicate`), both condition sets are copied and their `field_id` references remapped.

> **How do I make a field required, including a checkbox?**
>
> * In a signing request, select the field and enable **Required Field**. This control is available for checkbox fields too.
> * In a template, use **Required Field** for fields other than checkboxes. For a checkbox, this toggle is hidden and there is no dashboard control to make it unconditionally required. Use **Conditionally Required** only when another field should determine whether the checkbox is required.
>
> For conditional rules through the API, see [Conditional fields](/guides/conditional-fields).

> **How do I add initials on every page, or multiple signature fields for one signer?**
>
> * Add one **Initial** field to every page and assign each field to the signer.
> * In the template editor, to reuse a field on the current page, right-click it and select **Copy Field**. The copy stays on that page, so add a field separately on every page.
> * Ask the signer to fill each initials field. Empty initials fields are not filled automatically.
>
> Via the API, add one `initial` field per page in the `fields` array, each with its own `page_number`. A single recipient can have multiple required fields of the same type, including several `signature` fields.

> **How do I auto-fill the signing date, and what timezone does it use?**
>
> Use a `date` field to auto-fill the signing date.
>
> The field renders read-only in the signing view and fills with the signer's browser-local date when they finish, not a server timezone.
>
> * `date_signing_default: true`: enables auto-fill; there's no separate `date_signed` type.
> * `timezone`: the workspace setting checked first for certificate timestamps, defaulting to UTC until you set it.
> * `default_timezone`: the company-level fallback checked next, also defaulting to UTC until you set it.

> **Are templates shared across workspaces, and how do I copy one?**
>
> No, templates aren't shared across workspaces, not even within the same company.
>
> * `POST /templates/{id}/copy`: deep-copies the template's fields, recipients, CC list, reminders, custom field definitions, and document into another workspace, using a company-level (protected) API key.
> * `workspace_id`: the target workspace you pass in the request body.
> * `POST /templates/{id}/duplicate`: creates a new signing request from the template instead, not a copy of the template.

## Signing experience

> **Can I redirect the signer or customize the completion page after signing?**
>
> Yes, you can redirect the signer or customize the completion page after signing.
>
> * `completion_redirect_url`: redirects the signer after they finish signing.
> * `completion_title`: customizes the completion page title, set alongside the redirect URL.
> * `completion_message`: customizes the completion page message, set alongside the redirect URL.
> * `signing.completed`: the event to listen for instead, if you embed the signing view.
>
> **See:** [Completion page customization (API changelog v1.34.0)](/guides/api-changelog#completion-page-customization) and [Embeddable signing - postMessage events](/guides/embeddable-signing#postmessage-events)

> **Can I rename or hide signing buttons, or hide the language selector?**
>
> You can rename signing buttons and hide two of them. You cannot hide the language selector.
>
> Relabel button text per language with `signing_button_label_overrides`, using translation keys such as `common.finish`, `signing.approveAndFinish`, `signing.nextRequiredField`, `signing.saveAndFinishLater`, and `signing.decline.confirm`. Since v1.40.0, set `allow_decline` or `show_save_for_later` to `false` to hide **Decline to Sign** or **Save & Finish Later**. The language selector always renders.
>
> `disable_guided_navigation` turns off auto-scroll to the next field, shown in the dashboard as "Disable Auto-Scroll".
>
> **See:** [Workspace settings](/guides/workspace-settings)

> **Can I disable or customize the terms acceptance step?**
>
> Yes, you can both disable it and customize its text. The terms-acceptance gate can be turned on or off per workspace, or at the company level as the default. It's on by default. The consent banner text and its linked terms page are fully customizable per language from **Workspace/Company Settings > Terms**, for each of the 15 supported languages. Anything you don't set falls back first to your company's custom text, then to Firma.dev's own built-in terms banner, which is already localized into all 15 languages.
>
> **See:** [Legal validity](/guides/legal-validity)

> **Can signers correct their name or company before signing on forwarded links?**
>
> Yes, signers can correct their name or company before signing on forwarded links.
>
> Set `identity_editable_fields` on the signing request or template, for example `name` and `company`, so the signer can edit their own details before signing. A correction dialog appears right after they accept the terms, and every edit is written to the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How can signers sign, can I force hand-drawn signatures, and is Cyrillic supported?**
>
> Signers can draw or type their signature, you can require hand-drawn signatures, and Cyrillic is supported.
>
> Typing auto-detects the signer's script (Latin, Cyrillic, Greek, Japanese, Korean) from their name and offers matching font styles; there's no separate upload-an-image option. Set `hand_drawn_only` to `true` on the signing request or template to remove the Type tab and require drawing.
>
> Firma.dev does not support signer-supplied X.509 certificates; it applies its own PAdES seal to the completed document server-side.
>
> **See:** [Signing patterns](/guides/signing-patterns)

> **The signing page is blank or black. What should the signer try?**
>
> Ask the signer to hard-refresh the page. If that doesn't help, open the link in a recent Chrome, Firefox, or Safari with content and ad blockers disabled, since blockers can interfere with the signing page's scripts. On iOS Safari, make sure iOS and Safari are up to date and retry; older versions could run out of memory on very large or high-resolution PDFs.

> **Can I set the initial zoom of the signing page?**
>
> Yes, add `?zoom=` to the signing URL.
>
> **See:** [Embeddable signing - URL parameters](/guides/embeddable-signing#url-parameters)

> **Why does a signing link say invalid, expired, or already signed?**
>
> A signing link's error message depends on the signing request's state: not yet sent, expired, already completed by that recipient, or broken, mistyped, or cancelled.
>
> * Not sent yet: opening the link before the sender actually sends the request shows this message.
> * Expired: the request's `expiration_hours` window, measured from when it was sent, has passed; because a sent request can't be edited, the sender needs to create a new one instead of extending it.
> * Already signed: that specific recipient has completed their signature; it's tied to their own unique link, so it won't happen if a different signer opens their own link.
> * Invalid: a broken or mistyped link, or one for a cancelled request, produces its own distinct error rather than "already signed."

> **Can either of two signers sign, or can my own company auto-sign its side?**
>
> There is no built-in 'either-signer' mode; your application must decide who specifically signs before creating the request. An [organization seal](/guides/organization-seals) can apply your company's countersignature automatically, but every individual signer must still open their own link and complete the signing flow.
>
> **See:** [Signing patterns - Pattern: Parallel signing](/guides/signing-patterns#pattern-parallel-signing)

> **What happens if two signers share one email, or a signing link gets forwarded?**
>
> Nothing breaks. Each recipient's signing link is identified by their own recipient ID, not by email, so two signers can share the same email address without conflict, and forwarding a link doesn't let someone else become a different signer. If a link reaches the wrong person, `identity_editable_fields` lets the actual signer correct their own identity before signing, and that correction is recorded in the audit trail.
>
> **See:** [Signing patterns - Pattern: Dynamic second signer](/guides/signing-patterns#pattern-dynamic-second-signer)

> **How do I enable QR-code signing on a phone?**
>
> Use **QR Code on Signing Page** in Workspace Settings to control QR-code signing on a phone.
>
> QR codes are on by default; turning the setting off removes them. The QR code appears on the signing page; add the `{{signing_qr_code}}` placeholder to invitation templates to include it in emails.
>
> **See:** [Workspace settings: QR code in emails](/guides/workspace-settings#qr-code-in-emails-signing_qr_code)

## Identity verification (OTP)

> **How long is an OTP code valid, and why am I not asked for it again when I reopen the signing link?**
>
> An OTP code is valid for 10 minutes, with up to 3 attempts before you need to request a new one.
>
> Resending is rate-limited to once every 60 seconds, and these values are fixed: they aren't configurable per workspace or request.
>
> Once you verify a code, Firma.dev stores a session token in your browser and issues a fresh 4-hour signing session on each subsequent visit, so reopening the same signing link in the same browser within that window skips the OTP prompt. That rolling session is capped at 12 hours from your last successful verification, after which you'll be asked to verify again regardless of activity.

> **Does the completion certificate show that a signer used the one-time code?**
>
> Yes. Every signer row on the completion certificate carries an Authentication line: "Email Link" for a signer who signed without a one-time code, "Email Link + One-Time Code (code verified \<time>)" for a signer who entered the code. The request's Identity row shows the shared method, or "Mixed (see signers)" when signers differ. Exceptions: certificates issued before this feature was released show "Email Link" only in the Identity row, with no per-signer Authentication line; signers who verified before the release and did not reload the page print "Email Link"; a signer who verified the code before the release and reloaded the page only after it prints "Email Link + One-Time Code" without the "(code verified …)" time, for at most twelve hours after the release; a request whose one-time-code requirement was switched off while a signer was in progress may print "Email Link" (the link is kept only while that signer's session is carried forward); and when the server cannot confirm the link at finish (for example a lookup failure), the certificate prints "Email Link" rather than guessing.

> **Can I set a signing request's email/OTP language, or customize the OTP email?**
>
> You can set the OTP email's language per request, but not its wording. Set `language` on the signing request itself to override the workspace and company defaults for that request's signer-facing emails, including the OTP email. Custom email templates can't change the OTP email's wording, but you can skip OTP entirely per request by setting `settings.require_otp_verification` to `false`.
>
> **See:** [Localization](/guides/localization#email-language-settings), [White-Labeling](/guides/white-labeling#custom-email-sender-address)

> **Does Firma.dev support SMS OTP or national eID (BankID, MitID, FranceConnect)?**
>
> No. Firma.dev currently supports only email-based OTP for signer identity verification; there's no SMS OTP or national eID (BankID, MitID, FranceConnect, or similar) integration. Email OTP is included at no extra cost in Firma.dev's flat per-envelope pricing. This isn't stated anywhere as a near-term roadmap item, so treat it as not currently supported rather than something planned.

## Webhooks

> **Webhooks show enabled with zero failures, but nothing is delivered. Why?**
>
> This usually means the account-level webhook switch is off, even though the workspace shows enabled with zero failures.
>
> Turn it on under **Settings > Webhooks**, or through the API:
>
> * `PATCH /workspaces/{id}`: set `webhook_enabled` to `true` in the body to enable webhooks without the dashboard.
> * `ignore_company_webhooks`: make sure this isn't `true` on the workspace; it silently opts the workspace out of company webhooks.
>
> The dashboard test button bypasses the master switch, which is why tests succeed while real events are skipped with zero failures.
>
> **See:** [Webhooks](/guides/webhooks#two-levels-of-enablement)

> **How do company- vs. workspace-level webhooks differ for secrets, opt-out, and the viewed event?**
>
> Company- and workspace-level webhooks differ in their signing secrets, opt-out behavior, and how the viewed event fires.
>
> * Secrets: company- and workspace-level webhooks each have their own signing secret.
> * `ignore_company_webhooks`: lets a workspace opt out of its company's webhooks entirely, without affecting other workspaces.
> * `signing_request.viewed`: fires only on a recipient's first view, not on every subsequent open.
>
> **See:** [Webhooks](/guides/webhooks#handling-secret-rotation), [Webhooks](/guides/webhooks#two-levels-of-enablement), [Webhooks](/guides/webhooks#event-types)

> **Why do webhook deliveries fail with a redirect error?**
>
> Firma.dev does not follow HTTP redirects when delivering webhooks; this is deliberate SSRF protection, so a redirecting endpoint fails delivery outright. Register the exact URL your server serves; a mismatch in scheme, a `www` subdomain, the path, or a missing or extra trailing slash fails every delivery attempt.
>
> **See:** [Webhooks](/guides/webhooks#troubleshooting)

> **What's the webhook retry policy, timeout, and auto-disable threshold? Can I resend past events?**
>
> Your endpoint must answer with a 2xx within 5 seconds; failed deliveries are retried automatically, and the endpoint is disabled after 50 consecutive failures. You can retry a single event from the dashboard event log, but there is no bulk resend, and events from before the webhook existed are never backfilled.
>
> **See:** [Webhooks](/guides/webhooks#retry-behavior)

> **Should I poll GET /signing-requests/\{id} for status instead of using webhooks?**
>
> No, use webhooks instead of polling for status changes.
>
> * `GET /signing-requests/{id}`: don't poll this endpoint for status; webhooks push updates instead.
>
> **See:** [Rate Limits](/guides/rate-limits#best-practices-for-rate-limits), [Webhooks](/guides/webhooks)

## Email delivery & templates

> **What should I do if a recipient did not receive the signing email?**
>
> * In **Signing Requests**, confirm that the request is **In Progress**, not **Not Sent**. Open a draft and select **Send Request**.
> * Before sending, open **Settings** and enable **Send Signing Email**. Select **View details**, verify the address under **Signers**, and ask the recipient to check spam or junk.
> * For an in-progress request, select **Resend notification to next signer** in the request row. This sends to the next signer who has not completed their step.
> * To share access directly, select **View details**. Under **Signing Links**, select **Copy Link** for the signer and send it to them.
>
> If the address is suppressed, follow the removal steps in [Email deliverability](/guides/email-deliverability).

> **What does the RECIPIENT\_EMAIL\_SUPPRESSED (422) error mean, and how do I get an address unblocked?**
>
> `RECIPIENT_EMAIL_SUPPRESSED` (HTTP 422) means the recipient is on Firma.dev's suppression list; contact support to get an address unblocked.
>
> **See:** [Email Deliverability](/guides/email-deliverability#the-recipient_email_suppressed-error), [Requesting removal](/guides/email-deliverability#requesting-removal)

> **Can I customize the sender name and email address on signing invitations?**
>
> The sender name comes from the workspace name, falling back to the company name. The address uses your verified sending domain; set its local part with `email_local_part` at the company or workspace level.
>
> **See:** [Custom email sender address](/guides/white-labeling#custom-email-sender-address)

> **How do I stop the completion email, skip the certificate, or handle CC attachments?**
>
> Control these through the signing request's `settings` object:
>
> ```json theme={null}
> {
>   "send_finish_email": false,
>   "attach_pdf_on_finish": false,
>   "allow_download": false
> }
> ```
>
> * `send_finish_email: false`: stops the completion email.
> * `attach_pdf_on_finish: false`: sends a download link instead of attaching the PDF.
> * `document_only_download_url`: shares the document without the certificate, instead of `final_document_download_url`.
> * `certificate_only_download_url`: returns the certificate on its own.
> * `allow_download: false`: disables download links entirely, as a separate control from `attach_pdf_on_finish`.
>
> CC recipients receive the completed document as an email attachment under the same settings as the signer's copy.
>
> **See:** [Disabling Firma.dev emails](/guides/white-labeling#disabling-firma-emails)

> **What placeholders do email templates support, and can I customize them per language?**
>
> Custom templates use `{{placeholder}}` syntax.
>
> Legacy `[bracket]` syntax also works and is case-insensitive; an unresolved placeholder renders as nothing, not raw text.
>
> * `{{team_name}}`: an alias of `{{workspace_name}}`.
> * `{{team_email}}`: an alias of `{{workspace_email}}`.
> * `{{download_link}}`: resolves only in completion emails.
>
> No, templates don't vary by language: one template applies to every recipient, so per-language branded templates need a separate workspace each. There's no live preview or custom per-request variables.
>
> **See:** [Custom email templates](/guides/white-labeling#custom-email-templates)

> **Can I control the timezone or date format shown in emails?**
>
> Yes, through the API; the setting isn't exposed in the dashboard yet.
>
> * `timezone`: an IANA timezone set on the workspace through the settings API.
> * `default_timezone`: the company-level fallback when the workspace timezone isn't set.
>
> Placeholders such as `{{expiration_date}}` in signing emails use that timezone and the email's language. UTC remains the default when neither is set.
>
> **See:** [Supported timezones](/guides/workspace-settings#supported-timezones)

> **Why are signer emails in English when my workspace is set to another language?**
>
> * Open the workspace, then select **Settings > Email Templates** and set **Workspace Language**.
> * To override one request, open its **Settings** and set **Recipient email language**.
> * Change the dashboard interface separately with the language selector in the header, or **Language** in the mobile sidebar. This per-user setting does not change recipient emails.
>
> Via the API, language resolves per request, then workspace, then company. A company or workspace created through the API defaults to `en` unless you set `language` explicitly.
>
> **See:** [Email language settings](/guides/localization#email-language-settings)

## Custom sending domains

> **Which DNS records do I need, and what's the domain verify flow?**
>
> Setting up a custom sending domain requires a few DNS records added in two stages: one to verify ownership, then a few more to finalize. No MX record is needed at any step, since Firma.dev only sends mail through the domain and never receives it.
>
> **See:** [DNS records you'll need](/guides/custom-domains#dns-records-youll-need)

> **What does 'Domain conflict' or a stuck 'finalizing' status mean?**
>
> A 'Domain Conflict' status (or a stuck 'Configuring') means the domain is already registered under a different Resend account, often your own; the fix is a dedicated subdomain like `sign.yourcompany.com`, which verifies independently. Removing the domain from Firma.dev releases Firma.dev's own registration for reuse elsewhere, but has no effect on a registration in someone else's Resend account.
>
> **See:** [Already using Resend for your own email?](/guides/custom-domains#already-using-resend-for-your-own-email)

> **Why does domain status stay pending or unverified when DNS is correct?**
>
> Call `verify-dns` again; it checks live every time, so a transient hiccup can report the domain as unverified even when the DNS is correct.
>
> **See:** [Verification states](/guides/custom-domains#verification-states), [Known display quirk](/guides/custom-domains#known-display-quirk-pending-after-a-domain-is-already-verified)

> **Why did my verified domain stop working and emails fall back to Firma.dev's address?**
>
> A verified domain moves to 'Failed' when its DNS records stop checking out. Firma.dev only marks it invalid after two consecutive failed background checks, not the first blip, to avoid flapping on a transient hiccup. While a domain is failed or not yet verified, Firma.dev automatically sends from its own default domain instead of yours.
>
> **See:** [Verified domain later shows Failed](/guides/custom-domains#verification-states)

> **Can I use the same sending domain in more than one workspace?**
>
> Yes, add and verify the domain separately in each workspace where you want to use it.
>
> **See:** [Custom Domains](/guides/custom-domains), [Custom email domains](/guides/white-labeling#custom-email-domains)

## Legal validity / certificates / security

> **What signature level does Firma.dev provide, and is it legally valid under eIDAS/ESIGN?**
>
> Firma.dev provides an Advanced Electronic Signature (AES) under eIDAS Art. 3(11)/26, meeting the eIDAS admissibility floor and ESIGN Act/UETA requirements for most contracts; Firma.dev is not a Qualified Trust Service Provider and doesn't issue Qualified Electronic Signatures. The seal itself is `PAdES-B-LTA` (Baseline Long-Term Archival), issued from Firma.dev's own certificate authority, with an embedded RFC 3161 timestamp.
>
> **See:** [Legal Validity & eIDAS Compliance](/guides/legal-validity#what-firma-provides)

> **Why does Adobe Acrobat or the EU DSS validator show my signature as untrusted?**
>
> Firma.dev's digital seal is issued by Firma.dev's own certificate authority, not one chaining to Adobe's Approved Trust List (AATL) or the EU Trusted List (EUTL), so Acrobat and similar viewers won't show the automatic green checkmark; the seal itself is still fully valid. Verify it in your PDF viewer's signature panel, or independently at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature).
>
> **See:** [Why there's no green checkmark in Adobe Acrobat](/guides/legal-validity#why-theres-no-green-checkmark-in-adobe-acrobat)

> **Where is my data stored, and is Firma.dev SOC 2 / ISO certified?**
>
> Your data stays entirely within the EU, and Firma.dev is not SOC 2 or ISO 27001 certified, though its practices align with both frameworks.
>
> **See:** [Security & Compliance](/guides/security#data-residency)

> **How do I delete signing requests or documents, for example for a GDPR request?**
>
> * In **Signing Requests**, use the trash action for a draft and confirm **Delete Draft**.
> * For a sent request that is not completed, use the trash action and confirm **Cancel Request**.
> * In **Templates**, use the trash action for a template, then select **Delete** in the **Delete Template** dialog.
>
> You can also delete an unsent request through the API:
>
> ```text theme={null}
> DELETE /signing-requests/{id}
> ```
>
> Once a request has been sent it can no longer be deleted, only cancelled. A completed, signed document stays as the legal record and cannot be deleted or cancelled from the dashboard. The data a signer captured is never modified after signing, and there is no self-serve endpoint for removing a single signer's data from it. If you need a completed signing request removed to satisfy a data-protection request, contact support through **Help** in the dashboard sidebar.

> **In which language is the completion certificate generated, and can it show my logo?**
>
> The completion certificate is generated in your workspace's configured language, not the individual signer's language or a signing-request-level override, and yes, it can show your logo. It uses a fallback chain: workspace logo, then company logo, then Firma.dev's default logo, and it prints the workspace's own name. Certificate timestamps use the workspace's configured timezone, falling back to UTC if none is set.

> **Are archive timestamps renewed over time, and what happens if a signature is challenged?**
>
> No, and none is needed. Firma.dev applies its `PAdES-B-LTA` seal once, at signing time. The LTA profile embeds the full certificate chain, a trusted timestamp, and revocation data inside the PDF, so the signature carries everything a verifier needs and stays self-validating for the long term without any re-stamping on your side. If a signature is challenged, signer-identity, consent, and record-keeping responsibilities are set out in Firma.dev's Terms of Service.
>
> **See:** [Legal Validity: What Firma.dev provides](/guides/legal-validity#what-firma-provides), [Audit Trail](/guides/audit-trail)

> **Can I remove the Signing Request ID header from the signed PDF?**
>
> No, you can't remove the Signing Request ID header from the signed PDF.
>
> `Signing Request ID: <id>` is drawn on every page of the signed PDF and completion certificate, in small gray text near the top margin; there is no workspace or API setting to turn it off.
>
> The header is drawn with an embedded font, so sealed documents pass PDF/A-2b validation.

> **Is Firma.dev suitable for use in France: eIDAS, GDPR and HDS?**
>
> Firma.dev is suitable for most French use cases under eIDAS and GDPR, but not for HDS-regulated health data: Firma.dev does not hold an HDS (French health-data hosting) certification. Signatures are sealed as `PAdES-B-LTA`. For GDPR, Firma.dev acts as the data processor; the [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers, incorporated into the Terms by reference.
>
> **See:** [Security](/guides/security), [Legal Validity & eIDAS Compliance](/guides/legal-validity)

## Workspaces & multi-tenant

> **Should each customer get their own workspace? Is there a limit?**
>
> Yes, giving each end customer their own workspace is Firma.dev's recommended default for multi-tenant platforms; data in one workspace is never visible from another. There's no limit on how many workspaces you can create under one company, and no extra cost per workspace.
>
> **See:** [Multi-Tenant Architecture](/guides/multi-tenant#architecture-overview-company-workspaces), [Workspaces](/guides/creating-workspaces)

> **How do I change my company or workspace name?**
>
> * As an Owner, rename the company: go to **Account > Company Information**, select **Edit Company Details**, change **Company Name**, and select **Save**.
> * The protected default workspace follows the company name and cannot be renamed directly.
> * As an Owner, rename another workspace by opening it, selecting **Info**, changing **Workspace Name**, and selecting **Update Workspace**.

> **What is the protected/default workspace, and why do I get a 403 PROTECTED\_WORKSPACE error?**
>
> Every company gets exactly one default workspace, created automatically at signup and flagged `protected`.
>
> It's meant to be managed from the dashboard rather than the API; calling a management endpoint against it with a regular API key returns a `403` with code `PROTECTED_WORKSPACE`.
>
> For account-wide settings, use:
>
> ```text theme={null}
> PUT /company/settings
> ```
>
> This endpoint accepts `default_timezone` and `language`, among other fields. For anything you need to manage directly via the API, create separate, non-protected workspaces instead.
>
> **See:** [Workspaces: Edge cases & troubleshooting](/guides/creating-workspaces#edge-cases-troubleshooting), [Workspace Settings: Update workspace settings](/guides/workspace-settings#update-workspace-settings)

## White-labeling & embedding

> **What parts of Firma.dev can I white-label, and can I use my own API domain?**
>
> You can white-label signing-request emails, signer terms-acceptance text, and the signing page and embeds, but `api.firma.dev` itself can't be proxied under your own domain, only the email-sending domain is customizable. The completion certificate can also be white-labeled, with your logo replacing Firma.dev's. `show_custom_branding_only` only strips Firma.dev's support contact line from emails; it doesn't remove Firma.dev's presence from the signing page itself.

> **How do I set brand colors and a logo per workspace via the API?**
>
> Set workspace colors and a logo with these two endpoints:
>
> ```text theme={null}
> PUT /workspace/{workspace_id}/settings
> POST /workspaces/{workspace_id}/logo
> ```
>
> These settings apply across the signing page, embeds, and signing emails.
>
> **See:** [White Labeling](/guides/white-labeling#color-theming)

> **Why does the embedded template editor clip zoom/panning, and what about PDFs failing to load after a while?**
>
> Set `initialZoom` to control the embedded template editor's initial zoom directly.
>
> `autoFit` (boolean) is the alternative; `initialZoom` (number) takes precedence when both are set. Every document canvas supports panning via middle-mouse-button drag, leaving left-click free for field interaction.
>
> Signed document URLs expire after 1 hour. The embedded template editor auto-requests a fresh URL and retries up to 3 times instead of failing.
>
> If downloads are blocked, check for a `sandbox` attribute on your own page; Firma.dev's embed examples don't set one.
>
> **See:** [Embeddable template editor](/guides/embeddable-template-editor#configuration-options)

> **Can I inject custom CSS into embeds or embed just the signature box?**
>
> Neither is currently supported. Firma.dev's embeds (the template editor, signing-request editor, and the signing page) don't accept custom CSS, and there's no option to render only a signature field instead of the full document. If this is blocking your integration, share the use case with Firma.dev support.

## Tools / SDKs / limits

> **How do I connect Firma.dev's MCP servers, and which one should I use?**
>
> Firma.dev provides two MCP servers, the Data MCP for account access and the Docs MCP for documentation lookup; most developers connect both.
>
> **See:** [MCP Integration](/guides/mcp#setup)

> **Which SDKs does Firma.dev offer? Is there a Python SDK?**
>
> Firma.dev offers one official SDK, the TypeScript client `@firma-dev/sdk`, generated from the same OpenAPI spec as the API reference:
>
> ```bash theme={null}
> npm install @firma-dev/sdk
> ```
>
> There's no official Python SDK and no published roadmap commitment for one; call the REST API directly, for example with the `requests` library.
>
> **See:** [TypeScript SDK for the Firma.dev API](/guides/typescript-sdk#installation)

> **What are the API rate limits?**
>
> Rate limits are enforced per API key and vary depending on which operation you're calling.
>
> **See:** [Rate Limits](/guides/rate-limits#rate-limit-tiers)

> **Why do I see 'FunctionsFetchError: Failed to send a request to the Edge Function' in the console?**
>
> This client-side error means your browser's request to an edge function never reached the server:
>
> ```text theme={null}
> FunctionsFetchError: Failed to send a request to the Edge Function
> ```
>
> It comes from Supabase's JS SDK, for example due to an ad blocker, DNS filter, offline connection, or CORS block; it's a different error class than a genuine error response from the function itself.
>
> On Firma.dev's signing page, this most commonly comes from a background analytics call, which fails silently and doesn't affect your ability to view or sign the document.
>
> If it's happening on a call that's actually blocking your integration rather than analytics, check your network conditions before treating it as a Firma.dev-side error.

## For signers (received a document)

> **Where can I get a copy of a document after I sign it?**
>
> By default, everyone on the signing request, including CC'd recipients, is emailed a copy of the completed document once every signer has finished, not immediately after you personally sign. The email attaches the PDF automatically when it's under 8MB; larger files come as a download link instead. There's no signer login or dashboard to retrieve past documents yourself, so if you need a copy before everyone else has finished, ask the person who sent it to you (named in your invitation email).

> **I have a question about a document, want to undo my signature, or my link expired. What do I do?**
>
> Contact the sender named in your invitation email. Firma.dev is the e-signature platform they used to send the document, not a party to the agreement, so Firma.dev can't answer questions about its terms, resend an expired link, or act on the sender's behalf. If you haven't finished signing yet, you can decline the request instead; once you've signed, that signature is part of the permanent legal record and can't be undone by anyone, including Firma.dev support. Signing is always free for you: only the sender's account is billed.


# Field Prefilling
Source: https://docs.firma.dev/guides/field-prefilling

Pre-fill signing request fields with static text or recipient data, and understand which property actually controls the value.

Firma lets you show a signer a value before they ever open the document - either a fixed piece of text you choose, or a value pulled automatically from that recipient's own data (their email, name, company, etc). This guide covers the properties that control that behavior and the ones that only look like they do.

> [!WARNING]
>
> **Known spec issue:** the [Field schema](/api-reference/v01.33.00/signing-requests/create-signing-request) documents a top-level `prefilled_data` property with an enum of recipient attributes. **The server silently ignores it - it has no effect.** The only property that actually auto-populates a field from recipient data is `format_rules.prefilledData` (camelCase, nested inside `format_rules`), described below. If you've tried `prefilled_data` and the field came back empty, this is why. A spec correction is tracked separately; until then, use `format_rules.prefilledData`.

## Which property do I need?

* **The signer should type their own value, and you don't need to touch it** - don't set `read_only`. Just position the field normally.
* **You want a fixed value nobody can edit** (a contract number, a department name, anything you already know) - set `read_only: true` and `read_only_value: "..."`.
* **You want the recipient's own profile data shown and locked** (their email, name, company, etc.) - set `read_only: true` and `format_rules: { prefilledData: "..." }`.
* **You just need a label to identify the field later** (for your own bookkeeping, or to match a field when updating a template-based signing request) - that's `variable_name`. It never sets or changes what the signer sees.
* **You're reading a field back** (after creation, or after signing) and want the value that's actually there - read `value` in the API response.

## Property reference

| Property | Where it lives | What it does | Sets the displayed value? |
| :- | :- | :- | :- |
| `format_rules.prefilledData` | Nested inside `format_rules` on the field | The recipient-attribute key to auto-populate from. Set this to a recognized key and the field is filled from the assigned recipient's data at send time. Recognized keys: `email`, `first_name`, `last_name`, `full_name`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`, or a `custom_fields` key on the recipient. When set, the system also requires the matching attribute to be present on the recipient before allowing send. | Yes - the primary prefill mechanism |
| `read_only_value` | Top-level field property (request) | Static text you supply at field-creation time. **Cannot be combined with `prefilledData` when `read_only: true`** - the API returns 400. Without `read_only: true`, `read_only_value` silently overrides `prefilledData` instead of erroring. When a template already carries a `prefilledData` rule, `read_only_value` on the per-request field overrides the template's rule during merge. | Yes - always wins when present |
| `variable_name` | Top-level field property (request and response) | A developer-defined label for the field. Used as a **template merge key** (fallback after `template_field_id` when creating a signing request from a template) and as an **API accessor** to look up fields in `GET /signing-requests/{id}/fields` responses. Not involved in prefill resolution - that's `format_rules.prefilledData`. | No |
| `value` (response only) | Top-level field property, GET responses | The field's actual resolved/captured value - from `read_only_value`, from prefilled resolution, or from what the signer entered. `final_value` is a deprecated alias for the same data. | N/A - read-only, computed |

For fields created from a template custom field, `variable_name` contains an internal identifier. Use `variable_defined_name` to match the human-readable name you defined.

> [!NOTE]
>
> `format_rules.prefilledData` automatically locks the field for the signer and populates its value regardless of the `read_only` flag - unless `format_rules.prefilledEditable: true` is also set, which lets the signer edit the prefilled value. `read_only_value` also populates the value regardless of `read_only`. The `read_only` flag only matters for plain fields with no prefill and no `read_only_value` - it controls whether the signer can type into the field.

## Creating a signing request with prefilled fields

This example creates and sends a document with two locked fields: a static contract reference, and the recipient's email pulled from their own recipient record.

```bash cURL theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "fields": [
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 10, "width": 40, "height": 4 },
        "read_only": true,
        "read_only_value": "Contract #12345 - Acme Corporation"
      },
      {
        "type": "text",
        "recipient_id": "temp_1",
        "page_number": 1,
        "position": { "x": 10, "y": 18, "width": 40, "height": 4 },
        "read_only": true,
        "format_rules": { "prefilledData": "email" }
      }
    ]
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      fields: [
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 10, width: 40, height: 4 },
          read_only: true,
          read_only_value: 'Contract #12345 - Acme Corporation'
        },
        {
          type: 'text',
          recipient_id: 'temp_1',
          page_number: 1,
          position: { x: 10, y: 18, width: 40, height: 4 },
          read_only: true,
          format_rules: { prefilledData: 'email' }
        }
      ]
    })
  }
)

const result = await response.json()
```

```python Python theme={null}
import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'fields': [
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 10, 'width': 40, 'height': 4},
                'read_only': True,
                'read_only_value': 'Contract #12345 - Acme Corporation'
            },
            {
                'type': 'text',
                'recipient_id': 'temp_1',
                'page_number': 1,
                'position': {'x': 10, 'y': 18, 'width': 40, 'height': 4},
                'read_only': True,
                'format_rules': {'prefilledData': 'email'}
            }
        ]
    }
)

result = response.json()
```

> [!NOTE]
>
> `recipient_id` uses a temporary id (`temp_1`) here because the recipient is defined in the same request (document-based creation). If you're adding fields to an existing signing request or one created from a template, use the recipient's real UUID instead.

## Accepted `prefilledData` keys

`format_rules.prefilledData` accepts these recipient attributes:

`first_name`, `last_name`, `full_name`, `email`, `phone_number`, `company`, `title`, `street_address`, `city`, `state_province`, `postal_code`, `country`

You can also reference any key present in a recipient's `custom_fields` object (matched case-insensitively) - set that key when you create the recipient, then reference it the same way:

```json theme={null}
{
  "type": "text",
  "recipient_id": "temp_1",
  "page_number": 1,
  "position": { "x": 10, "y": 26, "width": 40, "height": 4 },
  "read_only": true,
  "format_rules": { "prefilledData": "employee_id" }
}
```

## Reading field values back

When you GET a signing request or list its fields, each field includes a `value` property - the actual resolved value, whether it came from `read_only_value`, from prefilled recipient data, or from what the signer typed. `final_value` still appears in responses but is a deprecated alias; prefer `value` in new integrations.

```json theme={null}
{
  "id": "field-uuid",
  "type": "text",
  "read_only": true,
  "format_rules": { "prefilledData": "email" },
  "value": "alice@example.com"
}
```

> [!NOTE]
>
> Prefill resolution happens at field-creation time once the recipient record exists, and is re-checked when the signing request is actually sent. If you use `create-and-send`, both steps happen atomically and the field's `value` is populated immediately in the response.

## Gotchas

### `variable_name` is a label, not a data source

`variable_name` is a UI-facing label and a matcher used when merging fields from a template into a signing request - it's never read as the source of a displayed value. Setting `variable_name: "email"` on a field does **not** prefill anything; you still need `format_rules.prefilledData` for that. Treat `variable_name` purely as an identifier you choose for your own reference.

### Signers can't override read-only or prefilled fields

If your integration renders its own signing UI and submits field values directly, any value submitted for a `read_only` or prefilled field is rejected server-side rather than silently accepted - the signer's submission is ignored for that field, and the attempt is logged as a security event. Don't rely on client-side hiding of these fields alone; the server enforces it independently.

### Prefilled fields block sending on missing recipient data

Any field prefilled with a standard key (`email`, `first_name`, `phone_number`, `company`, etc.) blocks sending if the assigned recipient is missing that attribute - regardless of whether the field is marked `required`. This is unconditional for the 12 standard keys.

For `custom_fields`-keyed prefill, the block only applies when the field is both `required: true` and `read_only: true` - a non-required custom-fields prefill that doesn't resolve simply leaves the field empty for the signer to fill.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) for the full recipient and field creation flow
* [Webhooks](/guides/webhooks) - subscribe to webhook events to track signing progress


# Gemini
Source: https://docs.firma.dev/guides/gemini-integration

Add legally binding e-signatures to any Gemini-powered app using function calling, the Gemini CLI, or Gemini Code Assist.

Firma lets you add legally binding e-signatures to anything built on Gemini. Use the Gemini API's function calling to let your AI agents send signing requests on demand, connect Firma's MCP servers to the Gemini CLI so the AI generates accurate integration code, or wire up webhooks to track completions. This guide covers all three.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Google AI Studio account with a Gemini API key, or Gemini Code Assist installed in your IDE
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from the Gemini API itself, which uses `x-goog-api-key`.

## Getting started

**Function calling**

Function calling lets a Gemini model decide when to call your code. You declare a function the model can call, and when the user asks it to send a contract, Gemini returns a structured tool call that your app executes against the Firma API.

This path is the right fit for AI agents, chatbots, and any app where a natural-language user request should turn into a signing request.

### Step 1: Store your API keys

Keep both your Gemini API key and your Firma API key in environment variables. Never put them in frontend code.

```bash theme={null}
GEMINI_API_KEY=your_gemini_key
FIRMA_API_KEY=your_firma_key
```

### Step 2: Declare a function and handle tool calls

Declare the function in the shape Gemini expects, then run a chat loop that handles the tool call by hitting Firma's `create-and-send` endpoint.

```javascript theme={null}
import { GoogleGenAI, Type } from "@google/genai";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const sendSigningRequestDeclaration = {
  name: "send_signing_request",
  description:
    "Send a document for e-signature via Firma. Uses a pre-configured template and one signer.",
  parameters: {
    type: Type.OBJECT,
    properties: {
      name: {
        type: Type.STRING,
        description: "A descriptive name for the signing request.",
      },
      template_id: {
        type: Type.STRING,
        description: "The ID of the Firma template to send.",
      },
      signer_email: { type: Type.STRING },
      signer_first_name: { type: Type.STRING },
      signer_last_name: { type: Type.STRING },
    },
    required: [
      "name",
      "template_id",
      "signer_email",
      "signer_first_name",
      "signer_last_name",
    ],
  },
};

async function sendSigningRequest(args) {
  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: args.name,
        template_id: args.template_id,
        recipients: [
          {
            first_name: args.signer_first_name,
            last_name: args.signer_last_name,
            email: args.signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    return { error: data };
  }

  return {
    signing_request_id: data.id,
    status: "sent",
    signing_link: data.first_signer?.signing_link,
  };
}

export async function handleUserMessage(userText) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: userText,
    config: {
      tools: [{ functionDeclarations: [sendSigningRequestDeclaration] }],
    },
  });

  const call = result.functionCalls?.[0];
  if (!call) {
    return { text: result.text };
  }

  const toolResult = await sendSigningRequest(call.args);

  const followUp = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      { role: "user", parts: [{ text: userText }] },
      { role: "model", parts: [{ functionCall: call }] },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: call.name,
              response: toolResult,
            },
          },
        ],
      },
    ],
  });

  return { text: followUp.text, result: toolResult };
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in a single API call. If you need the model to draft a request for review before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` once approved.

### Step 3: Wire it into your app

Call `handleUserMessage` from your backend whenever the user sends a chat message. Gemini decides on its own when the request warrants a signing flow:

```javascript theme={null}
// e.g. an Express handler
app.post("/chat", async (req, res) => {
  const reply = await handleUserMessage(req.body.message);
  res.json(reply);
});
```

A user message like "Send the consulting agreement to [alice@acme.com](mailto:alice@acme.com)" will trigger the function call. The model returns the structured `functionCall`, your code executes it against Firma, and the follow-up turn lets Gemini summarize the result back to the user.

### Python alternative

The same flow with the Python SDK:

```python theme={null}
import os
import requests
from google import genai
from google.genai import types

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

send_signing_request = {
    "name": "send_signing_request",
    "description": "Send a document for e-signature via Firma.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "A descriptive name for the signing request."},
            "template_id": {"type": "string"},
            "signer_email": {"type": "string"},
            "signer_first_name": {"type": "string"},
            "signer_last_name": {"type": "string"},
        },
        "required": [
            "name",
            "template_id",
            "signer_email",
            "signer_first_name",
            "signer_last_name",
        ],
    },
}

def execute(args):
    r = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": args["name"],
            "template_id": args["template_id"],
            "recipients": [
                {
                    "first_name": args["signer_first_name"],
                    "last_name": args["signer_last_name"],
                    "email": args["signer_email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    return r.json()

result = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Send the NDA template to bob@example.com (Bob Smith).",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[send_signing_request])]
    ),
)

call = result.function_calls[0]
print(execute(call.args))
```

**Gemini CLI via MCP**

Firma ships two MCP servers. Both work with the Gemini CLI. Connecting them turns Gemini into something that can both build Firma integrations and operate on your Firma data.

* **firma-api** (`https://mcp.firma.dev/mcp`) gives Gemini direct access to the Firma API - 84 tools across signing requests, templates, workspaces, and webhooks.
* **firma-docs** (`https://docs.firma.dev/mcp`) gives Gemini access to Firma's full documentation so it generates accurate integration code instead of guessing.

### Gemini CLI setup

Add both servers to your Gemini CLI settings. Use `~/.gemini/settings.json` for a global config, or `.gemini/settings.json` in your project for project-scoped access:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "httpUrl": "https://mcp.firma.dev/mcp"
    },
    "firma-docs": {
      "httpUrl": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. On first use of a Firma tool, Gemini will walk you through signing in with your Firma account via OAuth.

Once connected, you can ask the CLI things like:

* "List my pending signing requests in the Sales workspace"
* "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"
* "Add the Firma create-and-send endpoint to this Next.js project. Use the Firma docs for the exact request shape."

> [!WARNING]
>
> Gemini Code Assist for individuals is being sunset on June 18, 2026. Users on the individual tier should migrate to Gemini Code Assist Standard/Enterprise or the Gemini CLI. The MCP configuration works the same way across all tiers.

> [!NOTE]
>
> When to use which server: `firma-api` is for doing things (sending signing requests, managing templates). `firma-docs` is for building things (generating integration code with accurate API details). Most developers want both connected.

### Prompts that work well with the agent

**Generate a full backend integration:**

```text theme={null}
Using the Firma API docs, create an Express route that:
1. Accepts a name, template_id, signer email, and signer name
2. Uses the create-and-send endpoint to send a signing request
3. Returns the signing request ID and the signer's signing link
Store the API key in process.env.FIRMA_API_KEY.
```

**Add embedded signing to a React app:**

```text theme={null}
Using the Firma docs, add an embedded signing view to this React app.
After a signing request is created, render the signer's signing_link
in an iframe.
```

**Wire up webhooks:**

```text theme={null}
Using the Firma docs, create a webhook handler that listens for
signing_request.completed events and updates the contract status
in our Postgres database.
```

Referencing "the Firma docs" explicitly tells the agent to query the `firma-docs` MCP server before writing code. Without that, it may fall back to general knowledge and miss endpoint or auth details.

## Webhook integration

To track signing events in real time, register a Firma webhook pointing at an endpoint in your app. Here is a minimal handler for `signing_request.completed`:

```javascript theme={null}
// e.g. app/api/firma-webhook/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { type, data } = await req.json();

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your DB, trigger downstream automation, etc.
  }

  return NextResponse.json({ received: true });
}
```

In the Firma dashboard under **Settings > Webhooks**, register your endpoint URL. Firma sends events for all major state changes. See the [webhooks guide](/guides/webhooks) for the full event list and signature verification.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of opening a Firma-hosted page, the `create-and-send` response includes `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Tips

* **Use function calling for runtime agents, MCP for build time.** Function calling is what your deployed app uses to actually send documents. The MCP servers are what you and the Gemini CLI use to build that integration.
* **Pass `template_id` as a tool arg, not a free-form string.** Templates are the safest way to constrain what the model can send. Let the model pick a template ID from a short, named list you control.
* **Validate before sending.** For higher-stakes documents, branch on a confirmation step. Use `POST /signing-requests` to create a draft, surface it to the user, then call `POST /signing-requests/{id}/send` only after they confirm.
* **Workspaces for multi-tenant apps.** If you are building a SaaS product on top of Gemini, give each end customer their own Firma workspace so templates and usage stay isolated.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [MCP integration](/guides/mcp) - Full MCP server reference with all 84 tools
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# GitHub Copilot
Source: https://docs.firma.dev/guides/github-copilot-integration

Add legally binding e-signatures to any project using GitHub Copilot with Firma's Docs MCP server and custom instructions.

GitHub Copilot writes code directly into your repo across VS Code, Visual Studio, JetBrains, the Copilot CLI, and GitHub.com (in chat, code review, and the Copilot cloud agent). It doesn't host your app, it produces the code that ships to your platform. This guide shows you how to configure Copilot so the Firma integration code it generates is correct on the first pass.

This guide covers three setup steps:

1. **Connect the Firma Docs MCP** — Copilot reads accurate Firma endpoints and payloads while working
2. **Add a repo-wide instructions file** — Persistent Firma conventions every Copilot session in this repo picks up
3. **Reference patterns** — Code shapes Copilot should match for create-and-send, webhooks, and embedded signing

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* GitHub Copilot enabled in your IDE or via the Copilot CLI
* A repo where you want to add e-signatures

## Step 1: Connect the Firma Docs MCP server

Firma ships a [Docs MCP server](/guides/mcp) that exposes the full documentation as searchable tools. With it connected, Copilot queries real endpoints, current request shapes, and webhook payload schemas instead of guessing.

### VS Code (workspace-level)

Create or edit `.vscode/mcp.json` in your repo:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Reload the window. In the Copilot Chat panel, open the tools picker and confirm `firma-docs` shows up.

### Copilot CLI (global)

Add it to `~/.copilot/mcp-config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "http",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart the CLI. Run `/mcp show` to confirm the server is connected.

### JetBrains

Click the **GitHub Copilot icon** in the status bar, select **Edit Settings**, then navigate to **Model Context Protocol** and click **Configure**. Add the `firma-docs` server with the URL `https://docs.firma.dev/mcp`.

### Visual Studio

In the Chat pane, switch to **Agent mode**, click the **Tools picker** ("+"), and select **Add custom MCP server**. Enter `firma-docs` as the name and `https://docs.firma.dev/mcp` as the URL. Alternatively, add the entry directly to your project's `.mcp.json` file.

The Docs MCP is read-only and unauthenticated, so you do not pass an API key to it. It only provides documentation.

## Step 2: Add a repo-wide Copilot instructions file

`.github/copilot-instructions.md` is loaded automatically by Copilot Chat, the Copilot cloud agent, and Copilot code review across every supported environment. Drop Firma conventions here so Copilot always generates code that matches Firma's API contract.

Create the file at `.github/copilot-instructions.md` (or append to it if it already exists):

```markdown theme={null}
## Firma.dev e-signature integration

When generating code that sends, receives, or embeds Firma e-signatures, follow these conventions:

- API base URL: `https://api.firma.dev/functions/v1/signing-request-api`
- Auth: header `Authorization` set to the raw Firma API key (no `Bearer` prefix)
- The key lives in `FIRMA_API_KEY` as an env var. Call Firma from the backend only, never the browser. Never commit the value.
- Default to `POST /signing-requests/create-and-send` when sending from a template. Only use the two-step `POST /signing-requests` then `POST /signing-requests/{id}/send` flow when the user needs to review the draft before sending.
- Recipient object shape: `{ first_name, last_name, email, designation: "Signer", order: 1 }`
- For webhook handlers, branch on `payload.type` (e.g. `signing_request.completed`). The signing request object lives at `payload.data.signing_request`.
- For embedded signing, iframe `https://app.firma.dev/signing/{signing_request_user_id}` with `allow="camera;microphone;clipboard-write"`.
- When unsure about an endpoint or field shape, use the `firma-docs` MCP server. Do not guess.
```

Commit this file. From now on, any prompt like "add a Firma signing request when the user clicks Send Contract" will start with the right defaults baked in.

### Optional: path-specific instructions

If your repo has a clear backend boundary, add a more specific instruction file at `.github/instructions/firma.instructions.md`:

```markdown theme={null}
---
applyTo: "src/api/**,src/server/**"
---

# Firma API helpers

Place all Firma API calls in `src/server/firma/` as a small typed client module. Do not call `fetch` against `api.firma.dev` from any other directory. Backend routes that trigger signing should import from this module.
```

This is loaded only when Copilot is editing files that match the `applyTo` glob, keeping the global instructions short.

## Step 3: Reference implementation patterns

Copilot generates code in whatever language matches the surrounding files. The shapes below are the canonical Firma calls. The instructions file steers Copilot toward them and the MCP fills in current details.

### Create and send (TypeScript)

```typescript theme={null}
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function sendForSignature(opts: {
  templateId: string;
  signer: { firstName: string; lastName: string; email: string };
}) {
  const res = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
    method: "POST",
    headers: {
      Authorization: process.env.FIRMA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: opts.templateId,
      recipients: [
        {
          first_name: opts.signer.firstName,
          last_name: opts.signer.lastName,
          email: opts.signer.email,
          designation: "Signer",
          order: 1,
        },
      ],
    }),
  });

  if (!res.ok) throw new Error(`Firma error: ${res.status}`);
  return res.json();
}
```

### Create and send (Python)

```python theme={null}
import os
import requests

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

def send_for_signature(template_id: str, signer: dict) -> dict:
    res = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer["first_name"],
                    "last_name": signer["last_name"],
                    "email": signer["email"],
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    res.raise_for_status()
    return res.json()
```

### Webhook handler

```typescript theme={null}
export async function POST(req: Request) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update the matching record and trigger follow-up logic
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```

### Embedded signing iframe

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

## Copilot cloud agent

If your repo is set up for the Copilot cloud agent (the GitHub.com mode that opens its own PRs from an issue), the same `.github/copilot-instructions.md` file applies. Once the MCP and instructions are in place, an issue like "Add a Send Contract button to the customer detail page that sends a Firma signing request from template tmpl\_abc123" will turn into a PR that wires up the env var, the backend handler, the webhook route, and the UI button without further hand-holding.

Surface the webhook URL and template ID as TODOs in the PR description so the human reviewer can register the webhook in the Firma dashboard before merging.

## Tips for working with Copilot + Firma

* **Be specific in prompts.** "Use the Firma create-and-send endpoint" gets better results than "add e-signatures." The Docs MCP server helps, but specific prompts still produce more accurate code.
* **Reference the docs explicitly.** Starting a prompt with "Using the Firma docs" or "Check the Firma API documentation" tells Copilot to query the Docs MCP server before generating code.
* **Commit the instructions file first.** The `.github/copilot-instructions.md` file only takes effect after it's committed. Push it before asking Copilot to generate Firma code.
* **Test with real API calls.** After generating your integration code, test it against the Firma API with a real template and signer email to confirm the generated code works end-to-end.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [MCP integration](/guides/mcp) — full MCP server reference
* [API reference](/api-reference) — full endpoint documentation


# InsForge
Source: https://docs.firma.dev/guides/insforge-integration

Add legally binding e-signatures to any InsForge app using compute functions backed by the Firma REST API.

Firma lets you add legally binding e-signatures to any app built on InsForge. Because InsForge gives your coding agent compute, hosting, auth, and storage out of the box, you can drop Firma into an existing agent-built app by adding one compute function and one webhook handler.

This guide covers two integration paths:

1. **Compute function (per-app)** — Write a TypeScript function that calls the Firma REST API directly. Best for single apps or custom logic.
2. **MCP-assisted generation (agent-level)** — Connect the Firma Docs MCP server to your coding agent so it can write the integration for you against accurate API references.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An InsForge project with compute and storage enabled
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**Compute function**

This is the most direct approach. You write a TypeScript compute function that calls the Firma REST API.

### Step 1: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

The secret is encrypted and automatically available to your compute functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 2: Create a compute function to send signing requests

Create a new function in your InsForge project, or ask your coding agent to generate one. This function creates a signing request from a template and sends it in a single API call using the `create-and-send` endpoint:

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

export default async function handler(req: Request) {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const authHeader = req.headers.get("Authorization");
  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const token = authHeader.replace("Bearer ", "");
  const client = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    edgeFunctionToken: token,
  });

  const { data: userData } = await client.auth.getCurrentUser();
  if (!userData?.user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = Deno.env.get("FIRMA_API_KEY")!;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return new Response(JSON.stringify({ error: data }), {
      status: response.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(
    JSON.stringify({
      signing_request_id: data.id,
      first_signer_id: data.first_signer.id,
      signing_link: data.first_signer.signing_link,
      status: "sent",
    }),
    {
      status: 201,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    }
  );
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

The response includes `first_signer.id` (the `signing_request_user_id`) and `first_signer.signing_link`, which you will need if you want to embed the signing experience directly in your app.

### Step 3: Call the function from your app UI

Invoke the compute function from your frontend using the InsForge SDK:

```typescript theme={null}
import { insforge } from "@/lib/insforge";

const { data, error } = await insforge.functions.invoke(
  "sendSigningRequest",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

You can also ask your coding agent to wire this up: "When the user clicks Send Contract, call the sendSigningRequest function with the template ID and signer details from the form."

**MCP-assisted generation**

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your coding agent (Claude Code, Cursor, Codex, or any MCP-compatible client). This lets the agent search Firma documentation while you build, so it can generate integration code with accurate API details.

### Step 1: Add the Firma Docs MCP server

Add this MCP server to your agent's configuration:

```text theme={null}
https://docs.firma.dev/mcp
```

### Step 2: Store your API key as a secret

In your InsForge project dashboard, add a secret named `FIRMA_API_KEY` with your Firma API key as the value. See the [InsForge secrets documentation](https://docs.insforge.dev/api-reference/admin/create-a-new-secret) for details.

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from compute functions where secrets are kept secure.

### Step 3: Prompt your agent

Because InsForge is designed around agentic coding, this is the most efficient path: your agent reads the Firma docs through the MCP server, generates the compute function, and ships the integration in one pass.

Example prompt:

```text theme={null}
Create an InsForge compute function that sends a Firma signing request
using the create-and-send endpoint. Use the FIRMA_API_KEY secret for
authentication. Look up the Firma API docs via the MCP server for the
correct request and response format.
```

The agent will use the MCP server to look up the correct endpoint URL, request body shape, and response fields, then generate the compute function with accurate API details.

## Webhook integration

To track when documents are signed, set up a Firma webhook pointing to an InsForge compute function.

1. Create a new compute function to handle incoming webhook events.
2. In the Firma dashboard under **Settings -> Webhooks**, register a webhook pointing to your function's URL: `https://<your-app>.functions.insforge.app/<function-name>`.
3. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

```typescript theme={null}
import { createClient } from "npm:@insforge/sdk";

export default async function handler(req: Request) {
  const insforge = createClient({
    baseUrl: Deno.env.get("INSFORGE_BASE_URL")!,
    anonKey: Deno.env.get("ANON_KEY")!,
  });

  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    await insforge.database
      .from("contracts")
      .update({
        status: "signed",
        signed_at: new Date().toISOString(),
      })
      .eq("firma_signing_request_id", signingRequestId);
  }

  return Response.json({ received: true });
}
```

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types and payload structures.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your InsForge app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Legal Validity & eIDAS Compliance
Source: https://docs.firma.dev/guides/legal-validity

Where Firma's electronic signatures stand under eIDAS, ESIGN/UETA, and country-specific rules in Italy, Spain, France, and Germany - and what Firma does not provide.

> [!NOTE]
>
> This page explains the legal frameworks that apply to electronic signatures. It isn't legal advice. Whether a given document can be signed electronically - and which signature tier it needs - depends on the laws of the relevant jurisdiction and the specific document. Consult qualified local counsel for your use case.

**Quick answer:** Firma provides an **Advanced Electronic Signature (AES)** under eIDAS, with a full audit trail and a tamper-evident digital seal on every completed document. This is legally sufficient for the large majority of contracts, NDAs, HR documents, and commercial agreements across the EU and US. Firma is **not** a Qualified Trust Service Provider (QTSP) and does not issue **Qualified Electronic Signatures (QES)**. A small set of document types - real estate transfers, some employment terminations, notarized acts - require QES or a notary regardless of which e-signature provider you use.

## The three tiers of electronic signature under eIDAS

eIDAS (EU Regulation 910/2014) doesn't certify individual products as "compliant" or "non-compliant." Instead, Article 25 sets out three tiers of electronic signature, each with a different legal effect. Industry shorthand for the baseline tier is "Simple Electronic Signature" (SES) - the Regulation itself doesn't use that label, but defines the tier in Article 3(10).

| Tier | eIDAS basis | What it takes | Legal effect |
| - | - | - | - |
| Simple Electronic Signature (SES) | Art. 3(10) | Any data in electronic form attached to other data and used to sign - a typed name, a scanned signature image, a click-to-agree | Can't be denied legal effect or admissibility solely because it's electronic (Art. 25(1)), but no automatic presumption of equivalence to a handwritten signature |
| Advanced Electronic Signature (AES) | Art. 3(11), Art. 26 | Must be uniquely linked to the signer, capable of identifying them, created under their sole control, and linked to the signed data so any later change is detectable | Same admissibility floor as SES, but the identity link and tamper-detection make it materially harder to dispute in practice |
| Qualified Electronic Signature (QES) | Art. 3(12) | An AES created on a Qualified Signature Creation Device (QSCD), using a Qualified Certificate issued by a Qualified Trust Service Provider (QTSP) after identity verification | Art. 25(2): legally equivalent to a handwritten signature. Art. 25(3): automatically recognized in every EU/EEA member state |

Only QES carries the automatic "equivalent to handwritten" presumption and automatic cross-border recognition. AES and SES are still legally valid and admissible everywhere in the EU - they just don't carry that automatic presumption, so their evidentiary weight is argued on the facts if a signature is ever challenged.

## What Firma provides

Firma's signing process is designed to meet the **Advanced Electronic Signature** bar:

* **Signer identity capture** - every signer's name and email are recorded and linked to their signature, with optional one-time-passcode (OTP) verification as an additional identity factor.
* **Full audit trail** - every document view, field interaction, signature, and decline is logged with a timestamp, actor identity, and IP address. See the [Audit Trail guide](/guides/audit-trail) for the full event schema.
* **Tamper-evident digital seal** - on completion, Firma applies a PAdES digital seal (the ETSI standard signature format for PDFs) to the final document. The seal embeds the signing certificate, a trusted timestamp, and revocation information directly in the file, so it can be verified independently of Firma's own servers.
* **Certificate of completion** - a summary of the signing process is embedded in the final PDF alongside the seal.
* **EU-hosted infrastructure** - Firma's database and document-processing services run in EU data centers (Supabase and AWS Lambda both in `eu-west-3`).

Together, this gives you a signature that's uniquely linked to the signer, backed by an identity check, and provably unaltered since signing - the criteria that define an AES under Article 26.

## Electronic seals

eIDAS also defines electronic seals (Articles 35-36), the equivalent of electronic signatures but for legal persons (companies) rather than natural persons. The three-tier structure mirrors signatures:

| Tier | eIDAS basis | What it takes |
| - | - | - |
| Electronic Seal | Art. 3(25) | Data in electronic form attached to other data, used by a legal person to ensure origin and integrity |
| Advanced Electronic Seal | Art. 3(26), Art. 36 | Must be uniquely linked to the creator (the legal person), capable of identifying that person, created using data under the creator's control, and linked to the data so any later change is detectable |
| Qualified Electronic Seal | Art. 3(27) | An advanced seal created on a Qualified Seal Creation Device, using a Qualified Certificate issued by a QTSP |

Firma's organization seal is designed to meet the **Advanced Electronic Seal** bar:

* **Uniquely linked to the company** - each seal is bound to the company that created it, with a recorded attestation from an authorized representative
* **Identifies the company** - the company name, seal display name, and signatory title appear on the certificate of completion
* **Created under the company's control** - only company owners or holders of the company's protected API key can create, replace, or revoke a seal; the stored image is hash-verified before every application
* **Linked to the document** - the seal is applied as part of the PAdES digital seal on the completed PDF, so any later change to the document is detectable

Together, this gives you a seal that is uniquely linked to your company, backed by an attested authority chain, and provably unaltered since application - the criteria that define an advanced electronic seal under Article 36.

Organization seals applied by Firma are advanced electronic seals, not qualified ones; see the next section. Setup and API details are in the [Organization Seals guide](/guides/organization-seals).

## What Firma does not provide

To be direct about the boundary:

* **Firma is not a Qualified Trust Service Provider (QTSP).** It isn't on the EU Trusted List, and it doesn't issue Qualified Certificates.
* **Firma does not produce Qualified Electronic Signatures (QES) or Qualified Electronic Seals.** The digital seal on your completed documents is an AES-level seal, not a QES - it does not carry the Article 25(2) presumption of equivalence to a handwritten signature or the Article 25(3) automatic cross-border recognition that QES gets.
* **SOC 2 and ISO 27001 aligned.** Firma's security practices are designed around the SOC 2 Trust Services Criteria and ISO 27001 controls. See [Security & Compliance](/guides/security) for details.
* **No Adobe Approved Trust List (AATL) membership** - see [below](#why-theres-no-green-checkmark-in-adobe-acrobat) for what that means in practice.

If your use case specifically requires QES - a qualified certificate-based signature, typically obtained via a licensed QTSP with in-person or video identity verification - Firma is not the right tool for that document on its own.

## Electronic signatures in the United States: ESIGN and UETA

The US doesn't use eIDAS's tiered model. The federal ESIGN Act and the state-level Uniform Electronic Transactions Act (UETA, adopted by nearly every state - New York uses its own similar Electronic Signatures and Records Act instead) both work on the same principle: a signature or record can't be denied legal effect solely because it's in electronic form, provided the process shows:

* **Intent to sign** - the signer took an affirmative action to sign.
* **Consent to do business electronically** - particularly important for consumer transactions, where ESIGN requires specific disclosures about the right to receive a paper copy and withdraw consent.
* **Attribution** - the signature can be tied to the person who signed.
* **Record retention** - the signed record can be accurately reproduced later.

Because ESIGN and UETA aren't tied to a specific signature technology, Firma's AES-level process - identity capture, explicit signing action, tamper-evident seal, full audit trail - is well-positioned to satisfy all four elements for most business, consumer, and healthcare contracts under US law.

A narrow set of document types is excluded from ESIGN/UETA entirely and generally still requires a wet-ink signature: wills and testamentary trusts, certain family-law documents (divorce, adoption), court orders, notices of utility cancellation, notices of foreclosure or eviction, product recall notices, and documents required to accompany the transport of hazardous materials.

### Organization seals under ESIGN and UETA

US law does not separate seals from signatures. ESIGN (15 U.S.C. § 7006(5)) defines an electronic signature as any symbol or process adopted by a person with intent to sign, and a company is a person. ESIGN (§ 7006(3)) and UETA (§ 2(6), § 14) also recognise an electronic agent acting for a person, and UETA § 9 attributes its acts to that person.

An organization seal fits that model: by creating the seal and accepting the authority statement, the company adopts the process, and each application is the act of an agent it authorized. In the US the seal can therefore serve as the company's electronic signature and, on company documents, stand in for the signature of an employee acting on the company's behalf, such as a countersigning officer. The certificate still records it as "Applied automatically" with the company, the attester, and the timestamp, which is the attribution evidence UETA § 9 asks for. Whether that satisfies a statute or clause that requires a personal signature is a question for your counsel.

## Country-specific notes

These are the questions we hear most often from signers and senders in specific EU countries. They're general context, not a substitute for local legal advice.

### Italy

Italian users often ask whether Firma qualifies as *firma elettronica avanzata* (FEA) under Italian domestic law. eIDAS AES and Italy's domestic FEA concept are related but not identical - Italy's implementing rules (under the *Codice dell'Amministrazione Digitale* and AgID technical guidelines) impose additional technical requirements on FEA solutions for certain regulated use cases within Italy. Firma's signature meets the EU-wide eIDAS AES bar described above; we don't claim compliance with Italy's domestic FEA technical specification. Where Italian law requires *firma elettronica qualificata* (Italy's term for QES) or notarization - real estate transfers, for example - consult Italian counsel.

### Spain

Under Spain's Civil Code freedom-of-form principle and Ley 6/2020 (Spain's domestic implementation of eIDAS), an AES like Firma's is generally sufficient for private contracts and is admissible as evidence. Certain acts require a notarial deed (*escritura pública*) regardless of signature technology - real estate transfers, mortgages, and specific corporate resolutions are common examples. Those require an in-person notary, not any tier of electronic signature.

### France

French Civil Code Article 1367 (formerly 1316-4) ties an electronic signature's legal weight directly to the eIDAS tiers, and French courts have historically scrutinized whether the AES criteria - identity verification and tamper-detection - are actually met, more closely than in some other member states. That's one reason a complete audit trail and an identity-verification step (Firma supports OTP as an additional factor) matter specifically in France: if a signature is ever challenged, you want documented proof that the AES criteria were met, not just the label. Certain French acts still require a notarial deed (*acte authentique*) - real estate transfers and matrimonial agreements among them - regardless of signature tier.

### Germany

German civil law imposes strict statutory written-form (*Schriftform*) requirements on certain contract types. Where the law requires *Schriftform* under § 126 BGB, only a **Qualified Electronic Signature** - not an AES - can substitute for it electronically, under § 126a BGB. Firma's AES-level signature is not sufficient for those documents. Some statutory form requirements go further and exclude electronic form entirely, requiring a wet-ink signature regardless of tier - termination of an employment contract under § 623 BGB is a well-known example. For contracts not subject to a statutory form requirement - the majority of commercial agreements, NDAs, and consumer contracts, under German law's general freedom-of-form principle - AES is legally sufficient. If you're unsure whether your document falls under a *Schriftform* requirement, check with German counsel before relying on Firma alone.

## Why there's no green checkmark in Adobe Acrobat

Adobe Acrobat and Reader show a green checkmark automatically only for signatures whose certificate chains to a root on the **Adobe Approved Trust List (AATL)** - a curated list of certificate authorities that ship pre-trusted inside Adobe's software. Acrobat can also be configured to trust certificates chaining to the EU Trusted List (EUTL), the list of EU-recognized QTSPs.

Firma is neither an AATL member nor a QTSP on the EUTL, so the certificate behind Firma's digital seal doesn't chain to either list. Acrobat will typically show the seal as present, but without the automatic green checkmark - you may see a neutral or unverified trust indicator instead, even though the seal itself is fully valid.

This is a limitation of Acrobat's default trust store, not a defect in the signature. The seal is still cryptographically verifiable independent of Adobe:

* Recipients can check the signature panel in Acrobat/Reader to inspect the certificate directly.
* Anyone can independently verify a signed document's seal at [app.firma.dev/validate-signature](https://app.firma.dev/validate-signature) - Firma's public signature validator - without relying on any PDF viewer's trust store at all.

## What holds up as evidence

If a signature is ever disputed, what typically matters - under Article 25(1) eIDAS, ESIGN, or UETA alike - isn't a technology label by itself, but whether you can show who signed, when, with clear intent, and that the record hasn't changed since. Firma's combination of identity capture, a complete [audit trail](/guides/audit-trail), a tamper-evident PAdES seal, and an embedded certificate of completion is designed to answer exactly that, for both AES-sufficient use cases in the EU and ESIGN/UETA use cases in the US.

That said, no vendor can guarantee an outcome in litigation - sufficiency of evidence is ultimately decided by the relevant court or authority on the facts of the case. For high-value transactions, or any document that might fall under a QES, notarization, or statutory written-form requirement in your jurisdiction, confirm the requirement with local counsel before relying on Firma alone.

## Related guides

* [Audit Trail](/guides/audit-trail) - the full event schema behind every signing request
* [Webhooks](/guides/webhooks) - get notified in real time when a certificate is generated or a signature completes


# Localization
Source: https://docs.firma.dev/guides/localization

Firma supports 15 languages out of the box with automatic language detection, per-user persistence, and embed-friendly overrides.

Firma ships with complete localization in 15 languages, making it ready for teams across Europe and Latin America from day one.

## Supported languages

| Language | Code |
| - | - |
| English | `en` |
| Spanish | `es` |
| Italian | `it` |
| Portuguese | `pt` |
| French | `fr` |
| German | `de` |
| Greek | `el` |
| Russian | `ru` |
| Polish | `pl` |
| Czech | `cs` |
| Swedish | `sv` |
| Dutch | `nl` |
| Romanian | `ro` |
| Norwegian Bokmål | `nb` |
| Catalan | `ca` |

All UI elements — buttons, labels, notifications, emails, and error messages — are fully translated in each language.

***

## Email language settings

### In the dashboard

* Open a workspace, select **Settings**, then **Email Templates**, and set **Workspace Language**.
* To override the language for one request, open the request, select **Settings**, and set **Recipient email language**.
* To change the dashboard interface language, use the language selector in the header. On mobile, open the sidebar and select **Language**. This preference is saved for your user and does not change recipient emails.

### Via the API

You can control the language of outgoing signing notification emails via the API by setting a `language` field at the company or workspace level.

**Company level** — Sets the default email language for all workspaces:

```bash theme={null}
curl -X PATCH https://api.firma.dev/functions/v1/signing-request-api/company \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es" }'
```

**Workspace level** — Overrides the company default for a specific workspace:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "fr" }'
```

### Cascading hierarchy

Email language follows a cascading priority:

| Priority | Level | Description |
| - | - | - |
| 1 (highest) | Signing request | Language of the specific signing request |
| 2 | Workspace | Default for all signing requests in the workspace |
| 3 (lowest) | Company | Default for all workspaces in the account |

API-created workspaces default to English unless you set their `language` explicitly. Because a workspace always has a language value, its value takes precedence over the company language for that workspace's emails.

The `lang` query parameter changes only the signer-facing UI. It does not change notification or OTP email language. Notification dates use the workspace timezone, and completion certificates use the workspace language.

Firma currently supports email OTP only. SMS OTP and national eID systems such as BankID, MitID, and FranceConnect are not supported.

***

## How language detection works (embeddable UI)

Firma uses a 2-tier fallback system to select the right language for each embeddable.

### 1. Local storage

On return visits, Firma checks the browser's local storage for a cached language preference. This provides instant language selection without a network request.

### 2. Browser detection (default)

On a user's first visit, Firma automatically matches the language to their browser or system language setting. If the detected language isn't one of the 15 supported languages, Firma defaults to English.

***

## URL-based language override for embedded signing

You can force a specific language by appending the `lang` query parameter to any Firma URL:

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es
```

You can combine `lang` with other URL parameters like `zoom` (initial zoom level):

```
https://app.firma.dev/signing/{signing_request_user_id}?lang=es&zoom=1.0
```

This is useful when you want to:

* Link directly into Firma in the correct locale for your users
* Pre-select the language in embedded iframes
* Test the signing experience in different languages

See [Embeddable signing](/guides/embeddable-signing#url-parameters) for all available URL parameters.

### Supported values

Use the two-letter language codes from the table above: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Example: Embed signing in Spanish

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>
```

***

## Localization in embeddable components

Firma's embeddable components fully support localization:

* [**Embeddable signing**](/guides/embeddable-signing) — The signing interface renders in the detected or overridden language
* [**Embeddable template editor**](/guides/embeddable-template-editor) — Template creation and editing UI is fully localized
* [**Embeddable signing request editor**](/guides/embeddable-signing-request-editor) — The signing request configuration interface supports all 15 languages

### Non-persistent mode for iframes

When Firma is embedded in an iframe, language preferences operate in a non-persistent mode. This means the language is determined by:

1. The `lang` URL parameter (if provided)
2. The parent page's context

This prevents embedded Firma components from overwriting language settings in the host application. Use the `lang` query parameter to control the language explicitly in iframe contexts.

### Example: Dynamic language selection

```js theme={null}
function embedSigning(signingRequestUserId, locale) {
  const iframe = document.createElement('iframe')
  iframe.src = `https://app.firma.dev/signing/${signingRequestUserId}?lang=${locale}`
  iframe.style.cssText = 'width:100%;height:900px;border:0;'
  iframe.allow = 'camera;microphone;clipboard-write'
  iframe.title = 'Sign Document'
  document.getElementById('signing-container').appendChild(iframe)
}

// Use the locale from your application
embedSigning('user_123', 'fr')
```

***

## Best practices

* **`Use the lang parameter in embedded signing`** — Don't rely on browser detection in iframe contexts. Pass the language explicitly to ensure a consistent experience.
* **Match your application's locale** — When embedding Firma, pass the same locale your application is using so the signing experience feels seamless.
* **Let users choose** — For direct Firma links (e.g., in emails), omit the `lang` parameter and let Firma's automatic detection handle it. Users who have set a preference will see their chosen language.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) — Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) — Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) — Configure signing requests in your UI
* [White Labeling](/guides/white-labeling) — Custom domains, embedded experiences, and branding


# Lovable
Source: https://docs.firma.dev/guides/lovable-integration

Add legally binding e-signatures to any Lovable app using Edge Functions, Supabase, and webhooks.

Firma lets you add legally binding e-signatures to any Lovable application. Use Supabase Edge Functions to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Lovable Cloud (built-in backend)** — Store your API key in the Cloud Secrets panel and prompt Lovable to generate the integration. Best for new projects or builders who want the fastest path to a working integration.
2. **External Supabase** — For projects already connected to a standalone Supabase instance. Write Edge Functions manually and manage secrets via the Supabase CLI. Best when you need full control over your backend.
3. **AI-prompted integration** — Use Lovable's AI chat to scaffold the entire integration from natural language prompts. Works with both Lovable Cloud and external Supabase setups.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Lovable project with Lovable Cloud enabled (required for Edge Functions and secrets)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Lovable Cloud

Lovable Cloud provides a built-in Supabase backend, so you don't need a separate Supabase account. Secrets, Edge Functions, and database tables are all managed from within the Lovable editor.

### Step 1: Store your API key as a secret

1. Open your project in the Lovable editor
2. Click the **+** button next to the Preview panel
3. Select the **Cloud** tab
4. Scroll to **Secrets** and click **Add Secret**
5. Set the name to `FIRMA_API_KEY` and paste your Firma API key as the value
6. Click **Save**

The secret is encrypted and automatically available to your Edge Functions via `Deno.env.get("FIRMA_API_KEY")`.

> [!WARNING]
>
> Never hardcode your API key in frontend code or paste it into the Lovable chat.

### Step 2: Create a table to track signing requests

Prompt Lovable's AI chat to create the database table:

```text theme={null}
Create a Supabase table called "signing_requests" with these columns:
- id (uuid, primary key, auto-generated)
- firma_request_id (text, unique)
- user_id (uuid, references auth.users)
- template_id (text)
- status (text, default 'pending')
- created_at (timestamptz, default now())
- updated_at (timestamptz, default now())

Enable Row Level Security so users can only view their own signing requests.
```

Review and approve the SQL migration that Lovable generates.

### Step 3: Create an Edge Function to send signing requests

Prompt Lovable to create the Edge Function:

```text theme={null}
Create an Edge Function called "send-signing-request" that:
1. Accepts template_id, signer_email, signer_first_name, and signer_last_name in the request body
2. Verifies the user is authenticated via the Authorization header
3. Calls the Firma API at https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send using the FIRMA_API_KEY secret
4. Sends a POST request with template_id and a recipients array containing the signer details with designation "Signer"
5. Stores the result in the signing_requests table with the Firma signing request ID, user ID, and template ID
6. Returns the Firma API response
7. Handles CORS headers for browser requests
```

If you prefer to write the function manually, create a file at `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Create and send the signing request in a single API call
  const firmaResponse = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY")!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "sent",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Connect the function to your app UI

Prompt Lovable to wire up the frontend:

```text theme={null}
When the user clicks "Send Contract", call the send-signing-request Edge Function with the template ID, signer email, first name, and last name from the form. Show a success message with the signing request status, or an error message if the call fails.
```

Or call the function directly from your React component using the Supabase client:

```typescript theme={null}
import { supabase } from "@/integrations/supabase/client";

const { data, error } = await supabase.functions.invoke(
  "send-signing-request",
  {
    body: {
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    },
  }
);
```

## Path 2: External Supabase

If your Lovable project is connected to a standalone Supabase instance that you manage separately, the integration uses the Supabase CLI instead of the Lovable Cloud panel.

### Step 1: Store your API key

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

### Step 2: Create the signing requests table

Run the SQL from Path 1, Step 2 directly in your Supabase SQL Editor.

### Step 3: Create and deploy Edge Functions

Generate the function scaffold with the CLI:

```bash theme={null}
supabase functions new send-signing-request
```

Replace the contents of `supabase/functions/send-signing-request/index.ts` with the code from Path 1, Step 3. Then deploy:

```bash theme={null}
supabase functions deploy send-signing-request
```

The frontend integration is the same as Path 1, Step 4. For a more detailed walkthrough of the Supabase-specific setup, including database triggers and RLS policies, see the [full Supabase integration guide](/guides/supabase-integration).

## Webhook integration

To track when documents are signed, set up a Firma webhook that points to an Edge Function. This works the same way regardless of whether you use Lovable Cloud or an external Supabase instance.

### Create a webhook handler

If you're using Lovable's AI chat, prompt it:

```text theme={null}
Create an Edge Function called "firma-webhook" that:
1. Receives POST requests from Firma webhooks (no auth verification needed)
2. Parses the event type from the payload
3. Maps these Firma events to statuses: signing_request.completed -> "completed", signing_request.cancelled -> "cancelled", signing_request.expired -> "expired", signing_request.sent -> "sent", signing_request.recipient.signed -> "recipient_signed", signing_request.recipient.declined -> "declined"
4. Updates the matching row in the signing_requests table by firma_request_id
5. Returns { received: true }
```

Or create the function manually at `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(
      JSON.stringify({ error: "Missing signing request ID" }),
      { status: 400 }
    );
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

### Deploy and register the webhook

Deploy the function without JWT verification, since Firma webhook requests don't include Supabase auth headers:

**Lovable Cloud:** Prompt Lovable to deploy the Edge Function, then note the function URL. It will follow the pattern `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`.

**External Supabase:**

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Select the events you want to receive, such as `signing_request.completed` and `signing_request.recipient.signed`.

Firma sends events for all key state changes. See the [webhooks guide](/guides/webhooks) for the full list of event types, payload structures, and signature verification.

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on HMAC signature verification.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in an iframe inside your Lovable app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

You can prompt Lovable to build this into your UI:

```text theme={null}
Add an embedded document signing view. When a signing request is created, show an iframe pointing to https://app.firma.dev/signing/{signing_request_user_id} that takes up the full width of the content area with a height of 900px. Include camera, microphone, and clipboard-write permissions on the iframe.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices and postMessage event handling.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that you can connect to your Lovable account. This lets Lovable's AI chat search Firma documentation while you build, so it can help you write integration code with accurate API details.

To set it up:

1. Go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Set a descriptive name (e.g., "Firma Docs")
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Choose the authentication method (none is required for the public docs server)
6. Click **Add server**

This is for the build experience only and does not affect your deployed app. With the MCP connection active, you can prompt Lovable with requests like "Add a signing request status dashboard using the Firma API" and the AI will reference live documentation to generate more accurate code.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# MCP Integration
Source: https://docs.firma.dev/guides/mcp

Connect Firma to AI assistants like Claude, ChatGPT, Cursor, GitHub Copilot, and more using the Model Context Protocol (MCP)

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

* **Data MCP** (`https://mcp.firma.dev/mcp`) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
* **Docs MCP** (`https://docs.firma.dev/mcp`) - Gives AI assistants access to Firma's full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma's MCP servers to execute the right API calls or look up the right documentation on your behalf.

## Setup

**Data MCP**

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.

**Supported clients:**

* **Claude** - Claude Code, Claude Desktop, Claude.ai
* **ChatGPT** - Via Developer Mode connectors
* **Cursor** - Native MCP support
* **GitHub Copilot** - VS Code 1.101+
* **OpenAI Codex** - Via CLI or config
* **Other MCP clients** - Any client implementing the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)

**Claude Code**

Add the Firma Data MCP server via the CLI:

```bash theme={null}
claude mcp add --transport http firma-api https://mcp.firma.dev/mcp
```

Or add it to your Claude Code configuration (`.claude/settings.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**Claude Desktop**

Add the server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving. You'll be prompted to sign in with your Firma account on first use.

**Claude.ai**

> **[Add Firma to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The connector will appear in your conversation toolbar

**ChatGPT**

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

> **[Add Firma to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://mcp.firma.dev/mcp`
3. Complete the OAuth sign-in flow when prompted
4. The Firma tools will appear in your conversations

**Cursor**

> **[Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=firma-api\&config=eyJ0eXBlIjoidXJsIiwidXJsIjoiaHR0cHM6Ly9tY3AuZmlybWEuZGV2L21jcCJ9)**
>
> One-click install for Cursor IDE

Or add manually to your project-level config (`.cursor/mcp.json`) or global Cursor settings:

```json theme={null}
{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**GitHub Copilot**

Requires VS Code 1.101+ with GitHub Copilot enabled.

> **[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22firma-api%22%2C%22config%22%3A%7B%22url%22%3A%22https%3A%2F%2Fmcp.firma.dev%2Fmcp%22%7D%7D)**
>
> One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (`.vscode/mcp.json`):

```json theme={null}
{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}
```

You'll be prompted to sign in with your Firma account on first use.

**OpenAI Codex**

Add the server via the Codex CLI:

```bash theme={null}
codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp
```

Or add it to your `config.toml`:

```toml theme={null}
[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"
```

You'll be prompted to sign in with your Firma account on first use.

**Docs MCP**

The Docs MCP server provides read-only access to Firma's documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.

**Supported clients:** Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

**Claude Code**

```bash theme={null}
claude mcp add --transport http firma-docs https://docs.firma.dev/mcp
```

Or add it to `.claude/settings.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**Claude Desktop**

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude.ai**

> **[Add Firma Docs to Claude.ai](https://claude.ai/new#settings/customize-connectors)**
>
> Open Claude.ai Connector Settings

1. Click **Add Connector**
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**ChatGPT**

> **[Add Firma Docs to ChatGPT](https://chatgpt.com/settings/connectors)**
>
> Open ChatGPT Connector Settings

1. Click **Create** to add a new connector
2. Enter the server URL: `https://docs.firma.dev/mcp`
3. No authentication required

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**GitHub Copilot**

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp
```

Or add to `config.toml`:

```toml theme={null}
[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"
```

### What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

* **API reference** - Endpoint URLs, request/response shapes, authentication details
* **Integration guides** - Step-by-step instructions for each supported platform
* **Feature guides** - Webhooks, embedded signing, white labeling, email templates, and more
* **Code examples** - Working examples in Node.js, Python, and other languages

### When to use it

Reference "the Firma docs" in your prompts to tell the assistant to query this server:

```text theme={null}
Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.
```

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

## Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

**Signing Requests**

The core workflow tools for creating and managing signing requests.

| Tool | Description |
| - | - |
| `signing_requests_list` | List signing requests with filtering and pagination |
| `signing_requests_create` | Create a new signing request from a document or template |
| `signing_requests_create_and_send` | Create and send a signing request in one step |
| `signing_requests_get` | Get details of a specific signing request |
| `signing_requests_partial_update` | Update specific fields on a signing request |
| `signing_requests_update` | Full update of a signing request |
| `signing_requests_send` | Send a draft signing request to recipients |
| `signing_requests_cancel` | Cancel an active signing request |
| `signing_requests_resend` | Resend to specific recipients |
| `signing_requests_users_list` | List recipients on a signing request |
| `signing_requests_fields_list` | List fields on a signing request |
| `signing_requests_reminders_list` | List reminders for a signing request |
| `signing_requests_audit_list` | Get the audit trail for a signing request |

**Templates**

Create and manage reusable document templates.

| Tool | Description |
| - | - |
| `templates_list` | List templates with filtering and pagination |
| `templates_create` | Create a new template from a base64-encoded document |
| `templates_get` | Get details of a specific template |
| `templates_partial_update` | Update specific fields on a template |
| `templates_update` | Full update of a template |
| `templates_delete` | Delete a template |
| `templates_duplicate` | Duplicate a template into a new signing request |
| `templates_replace_document` | Replace the document on an existing template |
| `templates_users_list` | List recipients on a template |
| `templates_fields_list` | List fields on a template |
| `templates_reminders_list` | List reminders on a template |

**Workspaces**

Manage workspaces for multi-tenant isolation.

| Tool | Description |
| - | - |
| `workspaces_list` | List all workspaces |
| `workspaces_create` | Create a new workspace |
| `workspaces_get` | Get details of a specific workspace |
| `workspaces_update` | Full update of a workspace |
| `workspaces_partial_update` | Update specific fields on a workspace |
| `workspaces_api_key_regenerate` | Regenerate a workspace's API key |
| `workspaces_api_key_expire` | Expire pending API keys |
| `select_workspace` | Switch the active workspace for the session |

**Webhooks**

Configure webhook endpoints for real-time event notifications.

| Tool | Description |
| - | - |
| `webhooks_list` | List all webhooks |
| `webhooks_create` | Create a new webhook |
| `webhooks_get` | Get details of a specific webhook |
| `webhooks_update` | Update a webhook |
| `webhooks_delete` | Delete a webhook |
| `webhooks_test` | Send a test event to a webhook |
| `webhooks_rotate_secret` | Rotate the webhook signing secret |
| `webhooks_secret_status` | Check webhook secret rotation status |

**Company**

View and update company-level information.

| Tool | Description |
| - | - |
| `company_list` | Get company information |
| `company_update` | Full update of company details |
| `company_partial_update` | Update specific company fields |

**Email Domains**

Configure custom email domains for sending notifications.

| Tool | Description |
| - | - |
| `company_domains_list` | List company-level domains |
| `company_domains_create` | Add a company domain |
| `company_domains_get` | Get domain details |
| `company_domains_delete` | Remove a domain |
| `company_domains_verify_ownership` | Verify domain ownership |
| `company_domains_finalize` | Finalize domain setup |
| `company_domains_verify_dns` | Verify DNS records |
| `company_domains_set_primary` | Set as primary sending domain |
| `workspace_domains_list` | List workspace-level domains |
| `workspace_domains_create` | Add a workspace domain |
| `workspace_domains_get` | Get workspace domain details |
| `workspace_domains_delete` | Remove a workspace domain |
| `workspace_domains_verify_ownership` | Verify workspace domain ownership |
| `workspace_domains_finalize` | Finalize workspace domain setup |
| `workspace_domains_verify_dns` | Verify workspace domain DNS records |
| `workspace_domains_set_primary` | Set as primary workspace sending domain |

**Email Templates**

Customize the email notifications sent to signers.

| Tool | Description |
| - | - |
| `workspace_email_templates_list` | List workspace email templates |
| `workspace_email_templates_get` | Get a workspace email template |
| `workspace_email_templates_update` | Update a workspace email template |
| `workspace_email_templates_delete` | Reset a workspace email template to default |
| `company_email_templates_list` | List company email templates |
| `company_email_templates_update` | Update a company email template |
| `company_email_templates_delete` | Reset a company email template to default |
| `email_templates_defaults_get` | Get default email templates for a language |
| `email_templates_placeholders` | List available email template placeholders |

**Custom Fields**

Manage custom metadata fields on workspaces, templates, and signing requests.

| Tool | Description |
| - | - |
| `workspace_custom_fields_list` | List workspace custom fields |
| `workspace_custom_fields_create` | Create a workspace custom field |
| `workspace_custom_fields_update` | Update a workspace custom field |
| `workspace_custom_fields_delete` | Delete a workspace custom field |
| `templates_custom_fields_list` | List template custom fields |
| `templates_custom_fields_create` | Create a template custom field |
| `templates_custom_fields_delete` | Delete a template custom field |
| `signing_requests_custom_fields_list` | List signing request custom fields |
| `signing_requests_custom_fields_create` | Create a signing request custom field |
| `signing_requests_custom_fields_delete` | Delete a signing request custom field |

**JWT & Settings**

Generate JWT tokens for embedded editors and manage workspace settings.

| Tool | Description |
| - | - |
| `generate_template_token_create` | Generate a JWT for the embedded template editor |
| `revoke_template_token_create` | Revoke a template JWT |
| `jwt_generate_signing_request_create` | Generate a JWT for the embedded signing request editor |
| `jwt_revoke_signing_request_create` | Revoke a signing request JWT |
| `workspace_settings_list` | Get workspace settings |
| `workspace_settings_update` | Update workspace settings |

## Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

* **Ask the assistant to select a workspace** - e.g., "Switch to the Marketing workspace"
* **Let the assistant pass a workspace ID per request** - the assistant can include a `workspace_id` parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

## Example conversations

### List all signing requests

> "Show me all pending signing requests in my Marketing workspace"

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

### Create and send a signing request

> "Create a signing request from the NDA template and send it to [jane@example.com](mailto:jane@example.com)"

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

### Check signing status

> "What's the status of the signing request I sent to John last week?"

The assistant will search recent signing requests and return the current status, including which recipients have signed.

### Generate integration code

> "Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint"

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

## Rate limits

MCP requests are subject to the same [rate limits](/guides/rate-limits) as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

## Troubleshooting

### Tools not loading

If your client shows the server as connected but no tools appear:

* **Claude.ai / ChatGPT**: Try disconnecting and reconnecting the connector from Settings
* **Cursor / VS Code**: Restart the application after adding the configuration
* **Claude Desktop**: Restart the app - changes to `claude_desktop_config.json` require a restart

### Workspace not found

Make sure you've selected a workspace after connecting to the Data MCP. Use "List my workspaces" to see available options.

### Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client's settings. The Docs MCP does not require authentication.


# Mistral
Source: https://docs.firma.dev/guides/mistral-integration

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow using Firma's MCP Connector.

Add legally binding e-signatures to any Mistral agent, conversation, or Vibe workflow by registering Firma's MCP server as a Connector.

Firma exposes its API as an MCP server, which means a Mistral agent can send signing requests, list templates, and check signing status as native tool calls. This guide covers three integration paths:

1. **Register Firma as a Connector** - The native Mistral pattern. Register Firma's MCP server once, then use it across conversations, agents, and Vibe. Best for most use cases.
2. **Function calling with the Chat Completions API** - Define Firma operations as tools manually. Best when you want full control over the tool schema or aren't using Connectors yet.
3. **Custom Connector (inline auth)** - Pass the Firma MCP server URL and API key at conversation time without pre-registering. Useful for multi-tenant setups where each user has their own Firma key.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mistral account with API access to Studio (`https://console.mistral.ai`)
* At least one Firma template with signing fields configured
* The `mistralai` Python SDK: `pip install mistralai`
* The `requests` library (for Path 2): `pip install requests`

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Register Firma as a Connector

This is the cleanest path. You register Firma's MCP server once, and every Mistral surface - the Conversations API, the Agents API, and Vibe - can use Firma's tools immediately.

### Step 1: Register the Connector

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        name="firma",
        description="Send and manage e-signature requests via Firma",
        server="https://mcp.firma.dev/mcp",
        auth_type="api-key",
        auth_value=os.environ["FIRMA_API_KEY"],
    )
    print(f"Connector ID: {connector.id}")


asyncio.run(main())
```

The Connector is now centrally registered in your Mistral workspace. The Firma API key is stored encrypted and never reaches the model or the end user.

> [!WARNING]
>
> Never put `FIRMA_API_KEY` in client-side code or commit it to a repo. Store it in your deployment platform's secret manager and load it at runtime.

### Step 2: Use the Connector in a conversation

Pass the Connector ID in the `tools` array and let the model decide which Firma tool to call:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send a signing request for template tmpl_abc123 to Alice Johnson at alice@example.com."}
        ],
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

The model inspects the Connector's exposed tools, picks the right one (e.g., `signing_requests_create_and_send`), constructs the arguments from the user's message, and executes it.

### Step 3: Build a persistent Firma agent

For a reusable agent that always has Firma tools available, create it once and chat with it later:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    agent = await client.beta.agents.create_async(
        name="signing_agent",
        description="Sends and tracks e-signature requests with Firma.",
        model="mistral-large-latest",
        instructions=(
            "You help users send and track signing requests with Firma. "
            "Always confirm signer name and email before calling create_and_send. "
            "After sending, return the signing_request_id so the user can reference it later."
        ),
        tools=[{"type": "connector", "connector_id": "<firma_connector_id>"}],
    )
    print(f"Agent ID: {agent.id}")


asyncio.run(main())
```

The same agent is usable from Vibe and from your own product through the Conversations API.

## Path 2: Function calling with the Chat Completions API

If you'd rather define Firma tools yourself, expose them as functions on the Chat Completions endpoint. This works on any Mistral model that supports tool calling.

```python theme={null}
import json
import os
import requests
from mistralai.client import Mistral

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "create_and_send_signing_request",
            "description": "Create a signing request from a Firma template and send it to a recipient.",
            "parameters": {
                "type": "object",
                "properties": {
                    "template_id": {"type": "string"},
                    "first_name": {"type": "string"},
                    "email": {"type": "string"},
                    "last_name": {"type": "string"},
                },
                "required": ["template_id", "first_name", "email"],
            },
        },
    }
]


def create_and_send_signing_request(template_id, first_name, email, last_name=""):
    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": first_name,
                    "last_name": last_name,
                    "email": email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )
    response.raise_for_status()
    return response.json()


messages = [
    {"role": "user", "content": "Send template tmpl_abc123 to Alice Johnson, alice@example.com."}
]

completion = mistral.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = create_and_send_signing_request(**args)
print(result)
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. Only `first_name` and `email` are required for each recipient. If you want a model-mediated review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Path 3: Custom Connector (inline auth)

When you don't want to pre-register a Connector (e.g., each user has their own Firma API key), pass the MCP server URL and credentials inline:

```python theme={null}
import asyncio
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


async def main() -> None:
    response = await client.beta.conversations.start_async(
        model="mistral-large-latest",
        inputs=[
            {"role": "user", "content": "Send template tmpl_abc123 to Alice at alice@example.com."}
        ],
        tools=[
            {
                "type": "custom-connector",
                "connector_id": "firma",
                "authorization": {
                    "type": "api-key",
                    "value": os.environ["FIRMA_API_KEY"],
                },
                "tool_configuration": {
                    "type": "custom",
                    "url": "https://mcp.firma.dev/mcp",
                },
            }
        ],
    )
    for output in response.outputs:
        if output.type == "message.output":
            print(output.content)


asyncio.run(main())
```

This is useful for multi-tenant setups where each customer has a separate Firma workspace and API key.

## Webhook integration: react when documents are signed

Firma sends webhooks for every state change in a signing request. The typical pattern with Mistral agents is to receive the webhook in your own backend, then either update your database directly or hand the event back to an agent for follow-up actions.

Minimal handler in FastAPI:

```python theme={null}
import os
from fastapi import FastAPI, Request
from mistralai.client import Mistral

app = FastAPI()
mistral = Mistral(api_key=os.environ["MISTRAL_API_KEY"])


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Option A: update your database and move on.
        # Option B: hand the event to an agent for follow-up.
        await mistral.beta.conversations.start_async(
            agent_id="<signing_agent_id>",
            inputs=[
                {
                    "role": "user",
                    "content": (
                        f"Signing request {signing_request_id} was just completed. "
                        "Update the deal in our CRM and email the account owner."
                    ),
                }
            ],
        )

    return {"received": True}
```

Register the endpoint in Firma under **Settings > Webhooks**.

> [!WARNING]
>
> For production use, verify webhook signatures using your Firma webhook secret and HMAC-SHA256. Add this check at the top of your handler:

```python theme={null}
import hashlib
import hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)


@app.post("/webhooks/firma")
async def firma_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("x-firma-signature", "")
    if not verify_signature(body, signature, os.environ["FIRMA_WEBHOOK_SECRET"]):
        return JSONResponse(status_code=401, content={"error": "invalid signature"})
    payload = json.loads(body)
    # ... handle event
```

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Vibe: end-user e-signature workflows

Once the Firma Connector is registered in your Mistral workspace, Vibe users can invoke Firma directly from chat. Typical prompts:

* "Send the standard NDA to [alice@example.com](mailto:alice@example.com)."
* "What's the status of the contract I sent to Bob yesterday?"
* "List all signing requests that are still pending."

> [!WARNING]
>
> Use Mistral's human-in-the-loop approval flow if you want end users to confirm before the agent actually sends. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Embedded signing

If you want signers to complete documents inside your own product instead of opening the Firma-hosted page, read the signer ID from the create-and-send response and embed the signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Docs MCP for build-time assistance

For development inside Vibe or any MCP-aware coding tool, register Firma's [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp` as a separate Connector. The Docs MCP exposes search over Firma's complete documentation, so the model can answer accurate API questions while you're writing integration code. This is for the build experience and does not affect your running agents.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Mocha
Source: https://docs.firma.dev/guides/mocha-integration

Add legally binding e-signatures to any Mocha app using AI-generated backend functions and the Firma API.

Firma lets you add legally binding e-signatures to any Mocha application. Store your Firma API key as a secret, ask Mocha's AI to call the API from your backend, and your users can send signing requests directly from your app.

This guide covers how to integrate Firma using Mocha's built-in backend functions and secrets manager. Since Mocha is AI-driven, most of the integration can be done by prompting the AI with the right instructions.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Mocha account (the free plan includes 1 published app; paid plans add more published apps and custom domains)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your Firma API key as a secret

1. Open your project in Mocha
2. Go to **Settings → Secrets**
3. Add a new secret with the name `FIRMA_API_KEY` and paste your Firma API key as the value

Never paste your API key directly into the Mocha chat input. Always use the Secrets panel so the key is stored securely and never exposed in frontend code.

To get your API key, log in to the [Firma dashboard](https://app.firma.dev). Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.

## Step 2: Ask Mocha to build the signing request feature

Mocha generates backend code from natural language prompts. You don't need to write code yourself. Instead, paste the following prompt into the Mocha chat:

```text theme={null}
Add a feature that lets me send a document for e-signature using the Firma API. When the user fills in a form with a document name, signer's first name, last name, and email, call the Firma API to create and send a signing request.

Use these details:
- API endpoint: https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Method: POST
- Headers: Authorization set to the FIRMA_API_KEY secret (raw key, no Bearer prefix), and Content-Type: application/json
- Request body:
  {
    "name": "from the form (a descriptive name for the signing request)",
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {
        "first_name": "from the form",
        "last_name": "from the form",
        "email": "from the form",
        "designation": "Signer",
        "order": 1
      }
    ]
  }
- On success, show a confirmation message with the signing request ID from the response (data.id).
- On error, show the error message to the user.
```

Replace `YOUR_TEMPLATE_ID` with the ID of a template from your Firma dashboard. You can find it under **Templates** by clicking on a template and copying the ID from the URL.

Mocha's AI will generate the backend function, create the frontend form, and wire them together. Test it in the preview before publishing.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients in one call. If you need to review or modify the request before sending, ask Mocha to use `POST /signing-requests` to create a draft first, then `POST /signing-requests/{id}/send` separately.

## Step 3: Track signing status with webhooks

Firma can notify your app when a document is signed, declined, or expires. To set this up:

1. Ask Mocha to create an API endpoint in your app that accepts POST requests. Use a prompt like:

```text theme={null}
Add a backend endpoint at /api/webhook/firma that accepts POST requests. When it receives a request, parse the JSON body and check the "type" field.

If the type is "signing_request.completed", log the signing request ID from data.signing_request.id and update my database to mark the document as signed.

If the type is "signing_request.recipient.signed", log the recipient email from data.recipient.email.

Always return a JSON response { "received": true }.
```

2. After publishing your app, copy the webhook URL: `https://your-app.mocha.app/api/webhook/firma`
3. In the Firma dashboard, go to **Settings → Webhooks** and register this URL

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

See the [webhooks guide](/guides/webhooks) for all event types and payload details.

## Embedded signing

For apps where signers complete documents directly in your UI instead of via email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Ask Mocha to add an iframe that loads the signing URL:

```text theme={null}
Add a page that shows a document signing experience in an embedded frame. Use this iframe code:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Replace {signing_request_user_id} with the first_signer.id value returned from the signing request API.
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions and security best practices.

## Bonus: Use Custom Knowledge for better AI results

Mocha's Custom Knowledge feature lets you give the AI persistent context about your project. Adding Firma API details here helps Mocha generate more accurate code when you ask it to build signing features.

1. Open your project and go to the **Custom Knowledge** tab
2. Add the following:

```text theme={null}
This project integrates with Firma (firma.dev) for e-signatures.
- Firma API base URL: https://api.firma.dev/functions/v1/signing-request-api
- Authentication: Use the FIRMA_API_KEY secret in the Authorization header (raw key, no Bearer prefix)
- Main endpoint: POST /signing-requests/create-and-send with "name", "template_id", and "recipients" array
- Each recipient needs: first_name, last_name, email, designation (usually "Signer")
- The "name" field is required — it is a descriptive name for the signing request
- Firma docs: https://docs.firma.dev
```

This is optional but recommended. It means every time you ask Mocha to build or modify a signing feature, the AI already knows how Firma works.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Multi-Tenant Architecture
Source: https://docs.firma.dev/guides/multi-tenant

Structure Firma workspaces to give each of your customers an isolated, branded signing environment inside your own multi-tenant platform.

If you run a SaaS platform and want to offer e-signature as a feature to your own customers, Firma's company/workspace model maps directly onto a multi-tenant setup: one workspace per end customer, fully isolated and independently brandable. This guide covers the pattern end to end - where to read details, follow the links to the dedicated guides.

> [!NOTE]
>
> This is an architecture guide, not a full API reference. It focuses on how the pieces fit together for multi-tenant platforms. For exhaustive request/response bodies, follow the links to [Creating Workspaces](/guides/creating-workspaces), [White Labeling](/guides/white-labeling), and [Custom Domains](/guides/custom-domains).

***

## Architecture overview: company → workspaces

Firma's account hierarchy has two levels:

* **Company** - the billing entity. One company holds one Firma subscription, one primary API key, and account-wide defaults.
* **Workspaces** - organizational units inside a company. Each workspace has its own templates, signing requests, envelope usage, API key, and branding.

For a multi-tenant platform, **your Firma company is your platform, and each of your end customers gets their own workspace.** Templates, signing requests, and signer data in one workspace are never visible from another - there's no cross-workspace exposure of documents or data.

```
Your Firma Company (your platform, one subscription)
├── Workspace: Customer A   → templates, signing requests, branding, API key
├── Workspace: Customer B   → templates, signing requests, branding, API key
└── Workspace: Customer C   → templates, signing requests, branding, API key
```

Branding, terms, email templates, and several display settings follow a **company → workspace cascade**: set a baseline at the company level, then override per workspace only where a customer needs something different. A workspace setting left at `null` inherits the company value. This means onboarding a new customer only requires setting what's actually different for them - everything else falls back to your platform default. See [Settings hierarchy](/guides/white-labeling#settings-hierarchy) for the full cascade rules.

> [!NOTE]
>
> One workspace per end customer is the right default. Only split a single customer across multiple workspaces if they have genuinely separate teams or business units that need their own isolated template libraries and usage tracking - see [Workspaces](/guides/creating-workspaces).

***

## Provisioning a workspace per tenant

When a new customer signs up on your platform, create their Firma workspace as part of your own onboarding flow.

**1. Create the workspace**

Call `POST /workspaces` with your platform's master API key when a new tenant signs up:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme Corp" }'
```

The response includes the new workspace's `id`, live `api_key`, and `test_api_key`. Persist the workspace `id` against the tenant record in your own database - you'll use it for every subsequent API call scoped to that tenant.

**2. Apply branding**

Upload the tenant's logo and set their colors immediately after creation (see [Per-tenant branding](#per-tenant-branding) below), so the workspace never has a moment of looking unbranded.

**3. Store the workspace-scoped key**

Decide whether your backend will call Firma using your platform's master key (with `workspace_id` in the request body) or the workspace's own scoped key. See [API key isolation](#api-key-isolation-and-management) for the trade-off.

Full request/response shapes, listing, and updating workspaces are covered in [Creating Workspaces](/guides/creating-workspaces).

***

## Per-tenant branding

Each workspace can override your platform's default logo and colors, so every tenant's signers see that tenant's brand, not yours and not Firma's.

**Logo.** Upload a workspace-specific logo, which overrides your company-level logo for that workspace only:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/tenant-logo.png"
```

PNG or JPEG, up to 2 MB. Deleting the workspace logo falls back to your company-level logo, not to no logo - so set a sensible platform default when you onboard.

**Colors.** Set the workspace's color palette (`color_primary`, `color_background`, `color_card`, and others) via `PUT /workspace/{workspace_id}/settings`. This is the same settings resource used for other per-tenant display options like `show_signature_frame` and `show_qr_code`.

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

**Email support footer.** `show_custom_branding_only` is a company-level switch, not per-workspace. It strips Firma's support contact line from emails for your entire company; it does not change the signing page.

Full color reference, custom signer terms, and signing button label overrides are documented in [White Labeling](/guides/white-labeling#custom-branding).

***

## Per-tenant email domains

If a tenant wants signing invitations to come from their own domain (`noreply@sign.tenant.com`) rather than your platform's domain, set up a workspace-level email domain. Workspace domains override your company-level domain for that workspace only - everything else defaults to your platform's domain.

The verification flow is the same four-step process (add domain → verify ownership via TXT record → finalize → verify DNS) as company-level domains, just against workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize (get DNS records) | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |

> [!NOTE]
>
> Most multi-tenant platforms only need this for tenants who explicitly ask for it. Leaving it unset means the tenant's workspace simply inherits your platform's company-level domain (or Firma's default) - no action required for the common case.

For the exact DNS records, verification states, and how to resolve DKIM conflicts with other providers, see [Custom Domains](/guides/custom-domains). For the full request/response bodies of every domain endpoint, see [Custom email domains](/guides/white-labeling#custom-email-domains).

***

## API key isolation and management

Every workspace gets its own live and test API key at creation time, independent of every other workspace's keys and your company's master key.

**Two integration patterns:**

* **Master key, `workspace_id` in the body** - your backend holds one API key (the company's) and passes `workspace_id` on each request (creating templates, sending signing requests, etc.). Simpler to operate; one key to rotate. This is the right default for most platforms, since your backend is already the trust boundary between your tenants and Firma.
* **Per-tenant scoped keys** - issue each tenant's workspace key to that tenant directly (for example, if the tenant runs their own backend and calls Firma without going through your servers). Use this only when a tenant genuinely needs direct API access; it means you're now distributing and rotating N keys instead of one.

> [!WARNING]
>
> Never expose either kind of key to a browser. If a workflow needs to be triggered from your tenant's frontend, have it call your backend, which holds the key and calls Firma server-side.

**Rotating a compromised or leaked workspace key** without regenerating your entire company's key:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
 -H "Authorization: Bearer $FIRMA_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "key_type": "live" }'
```

This issues a new key and gives the old one a 24-hour grace period (`expires_at`) rather than killing it instantly, so in-flight integrations don't break mid-request. Once you've confirmed the new key works, expire the old one immediately instead of waiting out the grace period:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
 -H "Authorization: Bearer $FIRMA_API_KEY"
```

Both endpoints are rate-limited to 1 request/minute and rejected on your company's **protected default workspace**. A regular API key cannot manage that workspace through the API; use the dashboard instead. Regenerating `live` and `test` keys are independent operations; regenerating one never affects the other.

***

## Embedded editors per tenant

To let a tenant's own users create templates or configure signing requests without leaving your product, embed Firma's editors with a short-lived JWT rather than exposing any API key to the browser:

```js theme={null}
// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)
```

```html theme={null}
<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>
```

Because the JWT is generated for a specific template (and that template belongs to a specific workspace), the tenant boundary is enforced by the token itself - a token minted for Customer A's template can't be replayed against Customer B's data. The embedded editors inherit the workspace's color palette once configured - if no custom colors are set, they fall back to Firma's default palette. Set the `color_*` fields on workspace settings to apply your tenant's branding. A correctly-scoped token gives you tenant isolation; adding custom colors completes the white-labeling.

See [Embeddable Template Editor](/guides/embeddable-template-editor) and [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) for the full JWT generation flow, token lifecycle, and frontend integration (HTML and React). For embedding the signer-facing signing flow itself, see [Embeddable Signing](/guides/embeddable-signing).

***

## Putting it together

A typical multi-tenant onboarding flow, end to end:

1. Tenant signs up on your platform → `POST /workspaces` creates their Firma workspace.
2. Upload their logo and set their colors (or leave both unset to inherit your platform default).
3. If they ask for it, set up a workspace-level email domain and/or custom signer terms.
4. Your backend stores the workspace `id` against the tenant record and uses it (with your master API key) for every template, signing request, and webhook scoped to that tenant.
5. If the tenant's own users need to build templates or configure signing requests in-app, mint per-template JWTs and embed the editors.

## Related guides

* [Creating Workspaces](/guides/creating-workspaces) - workspace CRUD, listing, and the `protected` flag
* [White Labeling](/guides/white-labeling) - full branding, terms, email template, and embedding reference
* [Custom Domains](/guides/custom-domains) - DNS records, verification states, and DKIM conflict resolution
* [Embeddable Template Editor](/guides/embeddable-template-editor) · [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) · [Embeddable Signing](/guides/embeddable-signing)
* [Webhooks](/guides/webhooks) - track signing activity per tenant workspace


# n8n
Source: https://docs.firma.dev/guides/n8n-integration

Add legally binding e-signatures to any n8n workflow using the Firma community node or the HTTP Request node.

Add legally binding e-signatures to any n8n workflow. The **Firma community node** (`n8n-nodes-firma`) gives you a dedicated Firma node with 96 operations, a trigger node with automatic webhook management, and a native credential type. This guide covers three integration paths:

1. **Firma node** (recommended) — Select a resource and operation from dropdown menus. Built-in fields for recipients, settings, and document sources.
2. **Firma Trigger node** — Automatically registers a webhook with Firma when the workflow activates. Starts a workflow when a Firma event occurs (e.g. `signing_request.completed`).
3. **AI Agent tool** — The Firma node works as a native tool for n8n AI Agents, so the agent can send signing requests autonomously from natural-language instructions.

If you prefer not to install community nodes, see [Using the HTTP Request node instead](#using-the-http-request-node-instead) at the end of this guide.

This guide describes version 0.2.0 of the node. To update an installed node, go to **Settings > Community Nodes** in n8n.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* An n8n instance (Cloud or self-hosted, v1.0+). Path 3 (AI Agent tool) requires n8n v1.47+
* At least one Firma template with signing fields configured

## Install the community node

### From Settings

1. In n8n, go to **Settings > Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-firma`
4. Agree to the risks and click **Install**

### From the Workflow Editor

You can also install without leaving your workflow:

1. Open any workflow and click **+** to add a node
2. Search for **Firma** in the node search panel
3. If the node is not yet installed, n8n shows it under **Community Nodes** in the search results with an **Install** option
4. Select it to install and add it to your workflow in one step

After installation, the **Firma** and **Firma Trigger** nodes appear in the node panel.

> [!NOTE]
>
> For self-hosted n8n, you can also install manually: `cd ~/.n8n/nodes && npm install n8n-nodes-firma`, then restart n8n.

## Set up credentials

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Firma API**
3. Set the fields:
   * **API Key:** paste your Firma API key. Your account's main key is on the **Dashboard** page; each workspace's live and test keys are on that workspace's **Info** tab.
   * **Webhook Secret** (optional): paste your webhook signing secret if you plan to use the Firma Trigger node with signature validation. A secret is automatically generated when you enable webhooks for your workspace or company. To find it, go to **Workspace Settings > Webhooks** (or **Company Settings > Webhooks**) and copy the secret using the show/copy controls. If you need to rotate the secret later, click **Regenerate**; the old secret stays valid for a 7-day grace period. See the [webhooks guide](/guides/webhooks) for full setup.
4. Leave **Environment** set to **Production** unless you are connecting to a self-hosted or staging instance
5. Click **Save**

> [!WARNING]
>
> n8n encrypts credentials using your instance's `N8N_ENCRYPTION_KEY`. Never paste your API key directly into node fields. Always reference it through the credential so it stays out of exported workflow JSON.

## Path 1: Firma node

The Firma node lets you interact with the Firma API through dropdown menus instead of manually configuring HTTP requests.

### Send a signing request from a template

1. Add a **Firma** node to your workflow
2. Select your **Firma API** credential
3. Set **Resource** to **Signing Request** and **Operation** to **Create and Send**
4. Fill in:
   * **Name:** a name for the signing request (e.g. `{{ $json.contract_name }}`)
   * **Document Source:** Template
   * **Template ID:** the ID of your Firma template
5. Under **Recipients**, click **Add Recipient** and fill in:
   * **Email:** `{{ $json.signer_email }}`
   * **First Name:** `{{ $json.signer_first_name }}`
   * **Designation:** Signer
   * **Order:** 1
6. Optionally expand **Additional Fields** to set language or expiration, and **Settings** to control download permissions, OTP verification, or email notifications

The node creates and sends the signing request in one atomic call. The output includes the `id` of the new signing request for use in downstream nodes.

### Create a draft first, then send after approval

If you need a human review step before sending:

1. Use the **Create** operation (creates a draft, does not send)
2. Add an n8n **Wait** or approval node in the middle of your workflow
3. Use the **Send** operation in a later node, passing the signing request ID from the Create step

### Other common operations

| Operation | What it does |
| - | - |
| **List** | Get all signing requests with filters (status, date range, signer email). Toggle **Return All** to auto-paginate. |
| **Get** | Retrieve a single signing request by ID |
| **Download** | Get a signed download URL for the completed document |
| **Cancel** | Cancel a signing request that is in progress |
| **Get Audit** | Retrieve the audit trail for a signing request |
| **Get Users** | List all recipients and their signing status |
| **Upload** (Document) | Upload a PDF or DOCX of up to 50 MB and get an upload ID. Use it as **Uploaded Document IDs** on Create or on a template. **Add Document** takes the upload ID of a PDF |
| **Add Document**, **Reorder Documents**, **Update Document**, **Remove Document** | Manage the documents of a signing request or template that holds several documents |

The node supports 10 resources (Signing Request, Template, Document, Organization Seal, Webhook, Workspace, Company, Domain, Email Template, JWT) with a total of 96 operations. See the full list in the [API reference](/api-reference).

A signing request created from a template inherits the template's organization seals. To create it without them, turn on **Create Without Template Seals**.

> [!WARNING]
>
> **Disable Retry On Fail for write operations.** Firma's write endpoints (Create, Create and Send, Send, Resend) have no idempotency key. Auto-retrying these operations can create duplicate legally-binding signing requests. In the node settings, set **Retry On Fail** to **off** for workflows that use these operations.

### Wire it into a trigger

Connect the Firma node to whatever upstream trigger drives your workflow. Common patterns:

* **Form Trigger** > Firma: a customer fills an n8n form, the workflow immediately sends them a contract to sign
* **Webhook Trigger** > Firma: your app posts to an n8n webhook when a deal closes, n8n fires the signing request
* **Schedule Trigger** > database query > Firma: nightly batch of renewal contracts goes out automatically

## Path 2: Firma Trigger node

The Firma Trigger node starts a workflow when a Firma event occurs. Unlike a generic Webhook node, it automatically registers and deregisters the webhook with Firma when you activate or deactivate the workflow.

### Set up a trigger

1. Create a new workflow and add a **Firma Trigger** node as the trigger
2. Select your **Firma API** credential
3. In **Events**, select which events to listen for (e.g. `Signing Request Completed`, `Signing Request Recipient Declined`)
4. Optionally set **Workspace ID** to scope the webhook to a single workspace. Without it, the webhook receives events for all workspaces in the company.
5. Activate the workflow

When you activate the workflow, the trigger node automatically creates a webhook in your Firma account pointing to the n8n production URL. When you deactivate, it deletes the webhook. If an orphaned webhook from a previous activation exists, the node detects and reuses it.

### Available events

The trigger lists 34 webhook events. Firma sends 26 of them:

* **Signing Request**: created, sent, viewed, completed, expired, cancelled, deleted, updated, certificate generated, reminder sent
* **Recipients**: signed, declined, identity changed
* **Seals on signing requests**: seal applied, seal paused, seal swapped
* **Organization Seals**: created, updated, deleted, erased
* **Templates**: updated, used
* **Workspaces**: created, updated
* **Domains**: verified, verification failed

The other 8 are marked **(Not Sent)** in the list: Firma accepts them in a subscription but does not send them. They stay in the list so workflows that already selected them keep working.

### Branch on event type

Add a **Switch** node after the Firma Trigger to route on `{{ $json.type }}`. A common setup:

* `signing_request.completed` > update a record in your CRM, send a confirmation email, kick off provisioning
* `signing_request.recipient.declined` > notify sales
* `signing_request.expired` > re-send or move the deal to lost

To archive the signed document, add a Firma node after the Switch that uses the **Download** operation with the signing request ID from the trigger payload.

### Signature validation

If you added a **Webhook Secret** to your Firma API credential, the trigger node automatically validates the `X-Firma-Signature` header using HMAC-SHA256. It also supports `X-Firma-Signature-Old` for secret rotation grace periods. Events with invalid or missing signatures are rejected.

### HTTPS required

Firma's webhook API requires HTTPS URLs. n8n Cloud handles this automatically. For self-hosted instances, use a reverse proxy with TLS or a tunnel service during development:

```bash theme={null}
# Using cloudflared
cloudflared tunnel --url http://localhost:5678

# Using ngrok
ngrok http 5678
```

> [!WARNING]
>
> Firma gates webhook delivery behind a master switch at both the company and workspace level. If the trigger activates but never receives events, confirm that webhooks are enabled for your workspace in the Firma dashboard (**Workspace Settings > Webhooks**). The per-webhook **Test** button bypasses this switch, so a successful test does not guarantee real event delivery.

## Path 3: Firma as a tool for the n8n AI Agent

The Firma node has `usableAsTool` enabled, which means it works natively as a tool for the n8n **AI Agent** node. The agent can browse templates, create signing requests, check status, and more, all from natural-language instructions.

1. In your AI Agent workflow, add a **Firma** node as a tool input on the agent
2. Select your **Firma API** credential
3. Choose which resource and operation to expose (e.g. **Signing Request > Create and Send**)

To give the agent broader capabilities, add multiple Firma tool nodes with different operations:

* One for **Template > List** (so the agent can find the right template)
* One for **Signing Request > Create and Send** (so it can send documents)
* One for **Signing Request > Get** (so it can check status)

The agent decides when to call each tool based on the conversation context.

## Embedded signing

If your workflow ends with the signer completing the document inside another app rather than over email, fetch the recipient's `signing_request_user_id` from the API response and embed Firma's signing UI in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Using the HTTP Request node instead

If you prefer not to install community nodes, you can call the Firma API directly with the HTTP Request node and a Header Auth credential.

### Create a Header Auth credential

1. In the n8n editor, click the **Credentials** icon in the left sidebar
2. Click **Add Credential** and search for **Header Auth**
3. Set the fields:
   * **Name (credential name):** `Firma API`
   * **Name (header):** `Authorization`
   * **Value:** paste your Firma API key
4. Click **Save**

### Send a signing request

Add an **HTTP Request** node and configure it:

| Field | Value |
| - | - |
| **Method** | `POST` |
| **URL** | `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send` |
| **Authentication** | Generic Credential Type |
| **Generic Auth Type** | Header Auth |
| **Header Auth** | Firma API (the credential from above) |
| **Send Body** | On |
| **Body Content Type** | JSON |
| **Specify Body** | Using JSON |

Paste this into the **JSON** body field, using n8n expressions to pull values from upstream nodes:

```json theme={null}
{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need a human review step before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` in a later node after approval.

### Receive webhooks without the community node

Use an n8n **Webhook** trigger node and register its URL manually with Firma:

1. Create a new workflow with a **Webhook** node as the trigger. Set **HTTP Method** to `POST` and copy the **Production URL**.
2. In the Firma dashboard, go to **Settings > Webhooks**, click **Add webhook**, paste the n8n production URL, and select your events.
3. Add a **Switch** node after the Webhook trigger to route on `{{ $json.body.type }}`.

See the [webhooks guide](/guides/webhooks) for the full list of event types and signature verification.

## Bonus: MCP connection for AI-assisted building

Firma ships a [Docs MCP server](/guides/mcp) that you can connect to any MCP-capable client (Claude Desktop, Cursor, etc.) while building n8n workflows. It lets the AI search Firma documentation in real time, so generated configs reference the correct endpoints, fields, and webhook event names.

Add the server using the URL:

```text theme={null}
https://docs.firma.dev/mcp
```

This is for the build experience only and does not affect your deployed workflows.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Platform Updates
Source: https://docs.firma.dev/guides/platform-updates

A timeline of new features, improvements, and changes to the Firma platform

Stay up to date with the latest changes to Firma. This page documents platform-wide updates including new features, UI improvements, and expanded language support.

***

## October 19, 2026

### n8n Node 0.2.0

The Firma community node for n8n (`n8n-nodes-firma`) now covers the current Firma API:

* **Document > Upload** uploads a PDF or DOCX of up to 50 MB; create a signing request or template from the upload
* Signing requests and templates with several documents: add, reorder, rename or replace, and remove documents
* **Organization Seal**: list and read seals, their images, access log and applications, and revoke a seal
* Seal participants on create, and **Create Without Template Seals** for requests created from a template
* **Allow Decline** and **Show Save for Later** on signing requests, templates and workspace settings, Catalan in every language list, and the seven seal webhook events in the trigger
* Fixed operations that failed against the API: Update (Full) of signing requests and templates, the JWT token operations, custom field creation, and the company Update (Full)

Update the node in n8n under **Settings > Community Nodes**. See the [n8n guide](/guides/n8n-integration).

***

## October 18, 2026

### Damaged PDFs Are Refused

Firma now checks every uploaded PDF for pages with no valid content. Such a page shows up blank, and the completion certificate of a signed document that contains it could not be generated. Uploading one, in the dashboard, in the embedded editors, or through the API, now stops with "The PDF is damaged: one of its pages has no valid content. Repair or re-export the file, then upload it again." Nothing is created.

* Applies to new templates, replacing a template's document, new signing requests, and adding or replacing a document on a template or signing request
* Re-export the file from the application that created it, or save it again from a PDF editor, then upload it again
* See the [API changelog](/guides/api-changelog#v1-40-1) for `MALFORMED_PDF`

### Firma MCP Server Reports API Errors as Errors

When a Firma API call made through the [Firma MCP server](/guides/mcp) fails, for example with `400 MALFORMED_PDF` or `404 NOT_FOUND`, the tool result is now marked as an error (`isError: true`), so your AI assistant knows the action did not happen. The error body it receives is unchanged.

***

## October 17, 2026

### Signing Page Buttons

Choose whether signers see the **Decline to Sign** and **Save & Finish Later** buttons on the signing page. Each button can be shown or hidden for the whole company, a workspace, a template, or a single signing request, and the most specific setting wins.

* **Company**: **Settings > Company Settings**, under **Signing page buttons**. The two switches set the default for every workspace
* **Workspace**: a workspace's **Settings** tab, under **Signing page buttons**. Choose **Show**, **Hide**, or **Use company default**; the change is saved immediately
* **Template**: the document settings tab (page icon) in the template editor sidebar, below the QR code option. Choose **Show**, **Hide**, or **Use workspace default**, then save the template. A signing request copies the template's choice when it is created, so later template changes do not affect existing requests
* **Signing request**: the same settings in the signing request editor's document settings tab, before the request is sent
* Hiding **Decline to Sign** applies to signers and approvers alike, and Firma also refuses any decline, so the request can only be stopped by cancelling it. Hiding **Save & Finish Later** only removes the button

See the [API changelog](/guides/api-changelog#v1-40-0) for the `allow_decline` and `show_save_for_later` settings.

***

## September 17, 2026

### Catalan Language Support

Firma now speaks 15 languages. Catalan (`ca`) joins the existing fourteen across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, completion certificates, and the organization-seal statement and its lifecycle emails.

* Set the language per workspace, per company, or per individual signing request, via the dashboard or the API. This drives invitation and reminder emails and date formatting. The completion certificate follows the workspace language
* Unless the signing URL carries a supported `lang` code, the signing ceremony and the consent statement recorded at terms acceptance follow the signer's own browser language, detected automatically; a supported `lang` code on the signing URL sets the language instead
* Certificates render Catalan diacritics and the geminated L (l·l) correctly with embedded fonts
* Browsers reporting a Catalan regional or dialect tag (`ca-ES`, `ca-AD`, `ca-FR`, `ca-IT`, `ca-valencia`) are detected as `ca` automatically

See the [API changelog](/guides/api-changelog#v1-38-0) for the widened language enums.

***

## September 14, 2026

### Organization Seals

Automate your company's countersignature. An organization seal places a company stamp, display name, and signatory title on the completed PDF as a participant in the signing order, and the certificate of completion records it as "Applied automatically".

* **Company and workspace scopes**: manage seals under **Settings > Organization Seals** (company) or a workspace's **Settings > Organization Seals**, with one default per scope and sender override
* **Three creation modes**: upload a PNG, type the company name, or draw a mark, each with a recorded authority attestation
* **Placement anywhere in the order**: add a seal from the **Template Users** or **Signers** panel; the top slot applies at send, any other slot applies once the participants before it have finished
* **Revoke and swap**: revoke prospectively, optionally stop pending applications, and swap a paused seal for another from the request view
* **API and webhooks**: `seal_participants[]` on templates and signing requests, `/seals` management endpoints, and seven webhook events

See the [Organization Seals guide](/guides/organization-seals) for setup and the [API changelog](/guides/api-changelog#v1-37-0) for endpoint details.

***

## August 25, 2026

### Invoice Downloads

You can now download PDF invoices for your credit purchases directly from the transaction history. Go to **Account > Credits & Billing** and click **View** next to any purchase to open the invoice in a new tab.

* Works for all past and future credit purchases
* Invoices are fetched on demand from Paddle, so they always reflect the latest billing details including VAT corrections
* Available for both one-time and auto-recharge purchases

***

## August 7, 2026

### Completion Page Customization

You can now customize what signers see after they finish signing. Set a custom title, message, redirect URL, and redirect delay at the workspace, template, or individual signing request level.

* **Custom title and message** replace the default "Signature Complete!" heading and description with your own branded text
* **Auto-redirect** sends signers to your app or a confirmation page after a configurable delay (0-30 seconds)
* **Cascading settings** let you set company-wide defaults and override them per workspace, template, or signing request
* Configure completion settings in **Workspace Settings > Completion Page** or in the **template editor's Document Settings** tab
* Available via the API on all signing request, template, workspace, and company settings endpoints

See the [API changelog](/guides/api-changelog#v1340) for field details and validation rules.

***

## August 3, 2026

### Five New Languages: Czech, Swedish, Dutch, Romanian, Norwegian

Firma now speaks 14 languages. Czech (`cs`), Swedish (`sv`), Dutch (`nl`), Romanian (`ro`), and Norwegian Bokmål (`nb`) join the existing nine across the entire platform: the dashboard, the signer-facing signing experience, all signer emails, signer consent terms, date formatting, and completion certificates.

* Set the language per workspace, per company, or per individual signing request — via the dashboard or the API
* The full signer journey is localized: invitation and reminder emails, the signing ceremony, and the consent statement recorded at terms acceptance. The completion certificate follows the workspace language, not the request language.
* Certificates render Czech and Romanian diacritics correctly with embedded fonts
* Browsers reporting Norwegian as `no` or `nn` are detected as `nb` automatically

See the [API changelog](/guides/api-changelog#v1330) for the widened language enums.

***

## June 23, 2026

### Custom Signing Button Labels

You can now customize the button text in the signing view per workspace and per language. Rename "Finish" to "Confirm", "Decline to Sign" to "Reject", or any other label that fits your workflow.

* Configure in **Workspace > Settings > General** under "Signing Button Labels"
* Per-language tabs: set different labels for each of the 9 supported languages
* 9 customizable buttons: Finish, Approve & Finish, Next Required Field, Save & Finish Later, Decline to Sign, Decline Dialog Title, Cancel, Finish Anyway, Go Back
* Leave a field empty to use the default translation
* Labels are sanitized server-side (max 200 characters, no HTML)

See the [API changelog](/guides/api-changelog#v1260) for the `signing_button_label_overrides` field on workspace settings.

***

## June 14, 2026

### Editor Brand Colors

You can now theme the embedded template and signing-request editors with your own brand colors, not just the signing experience. Five new color controls join the existing palette so the editor chrome your users see on your pages matches your brand.

* Set in **Settings > Appearance**, with per-workspace overrides in **Workspace > Settings > Appearance**
* Five new colors: accent (highlights, active tabs, switches, primary controls), accent foreground (text/icons on accent), canvas (the surround behind the document page), muted surface, and muted text
* Live preview shows the editor chrome update as you pick colors
* Each color is optional: unset values inherit workspace → company → Firma default, so existing editors render unchanged
* Asymmetric-contrast warnings flag color pairs that may be hard to read

See the [API changelog](/guides/api-changelog#v1250) for the new `color_*` fields and the 11-key resolved palette.

***

## June 4, 2026

### Custom Signer Terms

You can now show signers your own terms and conditions before they sign, instead of the default Firma consent statement. Set a custom statement (and an optional link to your full terms) at the company or workspace level, in any of the supported languages.

* Configure in **Settings** (company default) and **Workspace > Settings** (per-workspace override)
* Per-language statements: the signer sees the terms in their signing language, falling back to the Firma default when no custom text is set
* Optional "require terms acceptance" gate gives you a per-workspace override of the company setting
* Acceptances are captured server-side with a content hash for the audit record

See the [API changelog](/guides/api-changelog#v1230) for the Signer Terms and company settings endpoints.

***

## May 29, 2026

### Stronger Signer Session Expiration

Signer sessions on OTP-protected signing requests now have a firm time limit. After a signer verifies their email with a one-time code, access stays valid through normal activity but can no longer stay open indefinitely. When the limit is reached, the signer re-verifies with a new code to continue, no action needed from senders.

* Applies to signing requests with OTP verification enabled
* A signer is re-prompted for a one-time code after 4 hours of inactivity, or 12 hours after their most recent verification, whichever comes first
* Re-verifying with a fresh 6-digit code starts a new session window
* Existing signing links continue to work unchanged

***

## May 13, 2026

### Custom Email Sender Address

You can now customize the local-part (before the @) of outgoing signing notification emails when using a verified custom domain. By default, emails are sent from `support@yourdomain.com`. Change it to any valid local-part, such as `noreply`, `signatures`, or `documents`.

* Configure at the company level in **Settings > General** to set the default for all workspaces
* Override per workspace in **Workspace > Settings > General**
* Workspace setting takes priority over company setting
* Requires a verified custom email domain to take effect
* Accepts lowercase alphanumeric characters, dots, hyphens, and underscores (1-64 characters)

See the [API changelog](/guides/api-changelog#v1210) for schema details.

***

## May 12, 2026

### Disable Auto-Scroll in Signing View

You can now disable the automatic scrolling behavior that guides signers to the next required field. When disabled, signers can navigate the document freely without the view automatically scrolling after completing each field. The "Next Required Field" button remains available for manual navigation.

* Available as a toggle in company settings, workspace settings, template editor, and signing request editor
* Cascading setting: signing request overrides workspace, which overrides company
* Set at the company level to apply across all workspaces, or override per workspace/template/signing request
* Also available via the API as `disable_guided_navigation` in settings

See the [API changelog](/guides/api-changelog#v1200) for schema details.

### Company & Workspace Logo Upload

You can now upload a custom logo for your company or individual workspaces directly from the Settings page. Logos appear on signing certificates and in signing notification emails.

* Navigate to **Settings > Appearance** to upload your company logo
* Override the company logo on a per-workspace basis in **Workspace > Settings > Appearance**
* Supported formats: PNG and JPEG, max 2MB
* Logos are displayed at a maximum of 180x50px on certificates, maintaining aspect ratio
* When no logo is set, certificates use the Firma default logo

### Certificate Fine Print Footer

The legal compliance text at the bottom of signing certificates has been refined for a cleaner, more polished appearance.

See the [API changelog](/guides/api-changelog#v1190) for the new logo management endpoints.

***

## May 7, 2026

### Guided Signing Flow

The signing view now guides signers through documents field by field. When a signer agrees to terms and the document loads, the first required field is automatically highlighted and scrolled into view.

* **Contextual field labels** - a floating indicator above the active field shows what action is needed (e.g., "Sign here", "Type text", "Select a date", "Upload file")
* **Auto-advance** - after completing a field, the view automatically moves to the next required field after a brief delay
* **Keyboard navigation** - signers can Tab through fields in reading order and press Enter to advance, enabling a fully keyboard-driven signing experience
* **Progress tracking** - a progress bar shows how many required fields have been completed out of the total

***

## May 6, 2026

### Signer Identity Confirmation

Signers can now review and edit their identity information before signing. When enabled, a confirmation dialog appears after agreeing to terms, allowing signers to verify or update their name, company, job title, phone number, and address.

* Configure which identity fields are editable per signing request or template
* Set per-signer overrides: inherit defaults, disable, or customize which fields each signer can edit
* Signature and initials are always created as part of the confirmation flow
* Changes are tracked in the audit trail and optionally trigger webhook/email notifications
* Prefilled document fields automatically update to match identity changes

See the [API changelog](/guides/api-changelog#v1180) for schema details.

***

## May 5, 2026

### Editable Prefilled Data Fields

Prefilled data fields can now be optionally editable by signers. Previously, fields populated from recipient data (like name, email, or custom fields) were always locked. You can now allow signers to modify these values during signing, useful when prefilled data serves as a default that the signer may need to correct.

* Enable via the "Allow signer to edit this value" checkbox in the template or signing request editor
* Also available via the API with `prefilled_editable: true` in field `format_rules`
* Fields are still auto-populated from recipient data, but signers can change the value
* Existing prefilled fields remain locked by default - no changes to current behavior

### Explicit Field Values via API

You can now set an explicit `value` on fields when creating signing requests via the API. This lets you pre-populate any field with a specific value, independent of prefilled data or read-only settings. When both an explicit value and prefilled data are set, the explicit value takes precedence.

* Set `value` on any field in `POST /signing-requests` or `POST /signing-requests/create-and-send`
* The API validates that fields use only one value source at a time (explicit value, prefilled data, or read-only value)

See the [API changelog](/guides/api-changelog#v1180) for the `prefilled_editable` property and field value details.

***

## April 28, 2026

### Partial Document Download

You can now download a snapshot PDF of signing requests that are still in progress. From the signing request detail panel, click the download button to get a PDF showing all fields completed so far, with an audit trail page listing each signer's status.

* Available for in-progress, cancelled, declined, and expired signing requests
* Only completed signers' fields are rendered; pending signers' fields are omitted
* An optional "IN PROGRESS" watermark can be enabled per workspace in workspace settings
* The PDF includes a per-signer status table and evidentiary framing

See the [API changelog](/guides/api-changelog#v1160) for the corresponding `GET /signing-requests/{id}/download` endpoint.

### Radio Button Rendering in Signing View

Radio buttons in the signing view now display as hollow circles. When selected, a green checkmark appears inside the circle, making it clear which option the signer has chosen.

### Partial Download Watermark Setting

A new toggle in workspace settings controls whether partial PDF downloads include a diagonal "IN PROGRESS — NOT YET EXECUTED" watermark. The setting defaults to disabled and can be overridden per workspace.

***

## April 16, 2026

### Workspace Webhooks

Workspaces can now have their own webhook endpoints, independent from company-level webhooks. Each workspace gets its own signing secret and can subscribe to the same events as company webhooks.

* **Independent webhook configuration** — Create, test, and manage webhook endpoints scoped to a specific workspace from the workspace settings tab
* **Workspace signing secret** — Each workspace generates and rotates its own webhook signing secret with a 7-day grace period, separate from the company secret
* **Ignore company webhooks** — Toggle to prevent company-level webhooks from firing for events in a workspace, allowing full webhook isolation per workspace
* **Event log** — View delivery history and retry failed events for workspace webhooks directly in workspace settings

See the [API changelog](/guides/api-changelog#v011500) for endpoint and schema details.

***

## April 12, 2026

### Approver and CC Recipient Designations

You can now assign three distinct roles to recipients in signing requests and templates:

* **Signer** — Signs the document with signature, initial, and signing date fields (existing behavior)
* **Approver** — Approves the document using dedicated approval fields: approval stamp, approval checkmark, and approval date. Approvers must complete all assigned approval fields before the signing request can finish.
* **CC** — Receives a completed copy of the signed document when all signers and approvers have finished. CC recipients cannot sign or have fields assigned.

The template and signing request editors now show separate sections for active participants (Signers and Approvers) and CC recipients. Designation is selected when adding a recipient, and field compatibility is enforced automatically — signer-only fields (signature, initial, signing date) are only available for Signers, and approval fields are only available for Approvers.

See the [API changelog](/guides/api-changelog#v011400) for schema details.

### Stamp Fields

New stamp field type for placing image stamps or company seals on documents. Stamps support two modes:

* **Creator-configured**: Set the field as read-only, upload a PNG image in the template or signing request editor, and it appears as a fixed stamp at signing time
* **Signer-fillable**: Leave the field editable, and signers upload their own stamp image (PNG, max 375KB) during signing

Stamps are embedded in the final signed PDF at the field's position. Available in both internal and embedded editors.

See the [API changelog](/guides/api-changelog#v011300) for field type schema details.

### PAdES-B-LTA Signatures

All signed PDFs now use PAdES-B-LTA (PAdES Baseline Long-Term Archival) signatures. This upgrade from PAdES-B-B provides long-term validation with embedded timestamps and certificate revocation information, ensuring signatures remain verifiable indefinitely — even after signing certificates expire.

***

## April 2, 2026

### Russian and Polish Language Support

Firma now supports Russian and Polish across the platform. You can set either language at the company, workspace, or user level. Signing flow emails, the signing interface, and the main application UI are all available in both languages.

### Referral Codes

You can now share referral codes from your dashboard. When the referred company makes its first credit purchase, both you and the new user receive bonus credits. Find your referral code and sharing link in the new referral card on the dashboard.

### Custom Field Variable Names in the API

API responses for template and signing request fields now include a `variable_defined_name` property — the human-readable name you defined when creating a custom field. You can also use `variable_defined_name` to target fields when creating signing requests from templates. See the [API changelog](/guides/api-changelog#v011201) for details.

***

## March 26, 2026

### MCP Integration for AI Assistants

You can now connect Firma to AI assistants like Claude using the Model Context Protocol (MCP). Once connected, you can manage templates, create and send signing requests, configure workspaces, and more through natural language conversations.

* Works with Claude Code, Claude Desktop, and Claude.ai
* Authenticate with your existing API key or via OAuth sign-in
* Full access to workspaces, templates, signing requests, webhooks, and company settings
* Switch between workspaces during a conversation
* Each tool call maps to one API request, subject to standard rate limits

See the [MCP Integration guide](/guides/mcp) for setup instructions and the [API changelog](/guides/api-changelog#v011200) for details.

***

## March 19, 2026

### File Upload Fields

A new `file` field type lets you collect file attachments from signers. Add a file upload field to any template or signing request, and signers can upload documents directly during the signing flow.

* Accepts images (JPG, PNG) and/or PDF files depending on your configuration
* Files are validated by content (magic bytes), not just file extension
* Maximum file size of 10MB per upload
* Configure accepted file types per field: images only, PDF only, or both
* Upload limit warnings shown in the template editor

See the [API changelog](/guides/api-changelog#v011100) for the `FileFormatRules` schema and field configuration details.

### Anchor Tags

Automatically place fields on documents using text markers. Embed anchor strings like `{{SIGN_HERE}}` or `{{DATE}}` in your PDFs, and Firma will find them and convert them into positioned fields during signing request creation. The anchor text is removed from the document after processing.

* Up to 100 anchor tags per signing request
* Control offset, size, and matching behavior per anchor
* Target specific occurrences or all matches of an anchor string
* Optionally skip missing anchors without errors
* Works alongside manually positioned fields

See the [API changelog](/guides/api-changelog#v011100) for the full `AnchorTag` schema and properties.

### Field Background Colors

Fields now support a background color property. Set a hex color (e.g., `#FFFDE7`) on any field to visually highlight it — useful for drawing attention to fields that need signer action or distinguishing field groups.

***

## March 10, 2026

### Conditional Fields

Fields on documents can now be conditionally visible and conditionally required based on what a signer enters in other fields. For example, a "Spouse Name" field can appear only when a signer checks "Married," or an address block becomes required only when "Ship to different address" is selected. Conditions use a flexible nested logic system (AND/OR groups) and evaluate in real-time as signers fill out the document. All conditions are enforced server-side on submission, so they can't be bypassed.

Available in the template editor, signing request editor, embedded editors, and the full REST API. See the [API changelog](/guides/api-changelog#v011000) for schema details.

### DOCX Document Support

Templates and signing requests now accept simple .docx files in addition to PDFs. Documents are automatically converted to PDF on upload — no extra steps needed. This works across the UI editors and the API (the document field accepts base64-encoded DOCX or PDF).

### Signature Verification Frames

Completed documents can now display a visual signature verification frame — a small purple pill overlay on each signature showing a truncated signer ID. This makes it easy to visually verify which signer placed each signature. The feature is on by default and can be toggled per-workspace or per-company in settings.

### Improved Invalid Link Experience

Signers who visit an expired, completed, or invalid signing link now see a clear, branded error page explaining what happened, rather than a generic error message. Works in both standalone and embedded contexts.

### Additional Improvements

* **Thicker drawn signatures** — pen width increased 25% for better legibility on completed documents
* **Signing request detail view** — new detail sheet accessible from the dashboard table

***

## March 5, 2026

### Passkey Sign-In

Sign in faster with biometric authentication. Register a passkey from your profile using Face ID, Touch ID, Windows Hello, or a hardware security key — then log in with a single tap.

* Register up to 10 passkeys per account
* Rename, manage, and remove passkeys from your profile
* Synced passkey support (iCloud Keychain, Google Password Manager)
* Device type indicators show whether a passkey is local or cloud-synced
* Tracks when each passkey was last used

### Signer Email OTP Verification

Add identity verification to your signing flow. When enabled, signers must enter a one-time code sent to their email before viewing or signing a document.

* Enable at the workspace or individual signing request level
* 6-digit codes with auto-submit, 10-minute expiry, and max 5 attempts
* Resend button with 60-second cooldown
* Email address is masked for privacy on the verification screen
* Sessions use a rolling 4-hour idle window plus a 12-hour maximum from the last verification; signers re-verify with a new code when either elapses

See the [API changelog](/guides/api-changelog#v010900) for the `require_otp_verification` setting details.

### Template Document Replacement

Swap the PDF on an existing template without losing your work. Upload a new version and all fields, signer assignments, and settings stay in place.

* Supports PDF and Word (.doc, .docx) uploads with automatic conversion
* Page count and dimension validation to keep fields aligned
* Works in both the main template editor and the embedded editor
* 60MB file size limit

See the [API changelog](/guides/api-changelog#v010900) for the `POST /templates/{id}/replace-document` endpoint.

### Custom Email Templates

Customize the emails Firma sends on your behalf. Edit the subject and body for each notification type with dynamic variable support.

* Five customizable templates: signing invite, next signer notification, expired, cancelled, and declined
* Insert variables like signer name, document name, signing link, expiration date, and workspace branding
* Badge indicates whether you're using a custom or default template
* Reset to default at any time
* Warning when a signing invite is missing the signing link variable

### Workspace Language Settings

Set a default language per workspace that controls which language system emails are sent in.

* Supported languages: English, Spanish, Italian, Portuguese, French, German, Greek
* Language cascades: signing request > workspace > company
* Affects all outgoing email notifications

### Auto-Purchase addition

Enhanced auto-recharge configuration with better credit management and a refreshed UI.

***

## February 24, 2026

### Hand-Drawn Only Signature Setting

You can now require hand-drawn signatures via the API by setting `hand_drawn_only: true` in your signing request settings. When enabled, signers cannot use typed or font-based signatures and must draw their signature directly. See the [API changelog](/guides/api-changelog#v010700) for details.

***

## February 18, 2026

### Hand-Drawn Signatures

Firma now supports hand-drawn signatures in the signing view. Signers can draw their signature directly using a mouse, trackpad, or touchscreen in addition to the existing typed signature option.

### Localization Guide

A new [Localization guide](/guides/localization) is now available in the documentation. It covers Firma's full multilingual support including the 3-tier language detection system, URL-based language overrides via the `?lang=` parameter, per-user language persistence, and localization behavior in embeddable components.

***

## February 17, 2026

### Embedded Editor Close Controls

Both the **Template Editor** and **Signing Request Editor** now support a built-in close button and programmatic close, giving you full control over the editor lifecycle within your application.

* **Close button** — Enable `showCloseButton` to display a close button in the editor header. When clicked, your `onClose` callback receives `{ hasUnsavedChanges: boolean }` so you can prompt users to save before navigating away.
* **Programmatic close** — Call `triggerClose()` on the editor instance to close it from your own UI (e.g., a navigation event or "back" button). It checks for unsaved changes automatically.

These options are available on both `FirmaTemplateEditor` and `FirmaSigningRequestEditor`. See the [embeddable template editor](/guides/embeddable-template-editor) and [embeddable signing request editor](/guides/embeddable-signing-request-editor) guides for full details.

***

## February 11, 2026

### Multi-Script Signature Support

Firma now supports 5 international writing systems for typed signatures with automatic script detection and curated signature fonts.

**Supported scripts:**

| Script | Languages | Signature Font |
| - | - | - |
| Latin/Western | English, Spanish, French, German, Portuguese, Italian, Polish, Czech | Default signature fonts |
| Cyrillic | Russian, Ukrainian, Bulgarian, Serbian | Marck Script |
| Greek | Greek (including accented characters like ά, έ, ί, ό) | Zen Kurenaido |
| Japanese | Hiragana, Katakana, Kanji | Zen Kurenaido |
| Korean | Hangul | Nanum Pen Script |

Each script family includes multiple signature style options with hand-picked fonts. The system automatically detects the signer's script based on their typed name, though signers can manually switch if needed.

All signatures render correctly in completion certificates and final PDFs.

### Greek Language Support

The Firma interface is now fully available in Greek, bringing the total to 7 supported languages:

* English
* Spanish
* Portuguese
* French
* Italian
* German
* **Greek** (new)


# Rate Limits
Source: https://docs.firma.dev/guides/rate-limits

Firma.dev is designed for very high volume e-signing API usage. Each Firma.dev account may have unlimited workspaces with unlimited API keys, providing horizontal scalability.
All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are enforced per API key (this means per workspace) and vary by operation type.

### Rate Limit Tiers

| Operation Type | Rate Limit | Endpoints |
| :- | :- | :- |
| **Read Operations (GET)** | 200 requests/min | List/get company, workspaces, templates, signing requests, settings |
| **Write Operations (POST/PUT/PATCH/DELETE)** | 120 requests/min | Create/update/delete workspaces, templates, signing requests, company info, settings |
| **Webhook CRUD Operations** | 60 requests/min | Create, update, delete webhooks |
| **Webhook Test** | 10 requests/min | Send test webhook |
| **API Key Regeneration/Expiration** | 1 request/min | Regenerate or expire workspace API keys |
| **Webhook Secret Rotation** | 1 request/min | Rotate webhook signing secret |
| **Signer Signature Retrieval** | 60 requests/min | Retrieve a signer's signature, initials, stamp, or uploaded file |
| **Document Set Mutation** | 30 requests/min | Add, replace, reorder, rename, or remove documents |
| **Organization Seal Writes** | 10 requests/min | Create, replace, revoke, rename, or select organization seals |

For example, on the table above, you may have 200 GET's per minute per API key. Each [workspace](/guides/creating-workspaces) has it's own API key.

### Rate Limit Headers

Every API response includes headers showing your current rate limit status:

```http theme={null}
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1734451200
```

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | Maximum requests allowed per minute for this endpoint |
| `X-RateLimit-Remaining` | Number of requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

### Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

**Additional Header:**

```http theme={null}
Retry-After: 45
```

The `Retry-After` header indicates how many seconds to wait before retrying.

### Best Practices for Rate Limits

1. **Monitor rate limit headers** - Check `X-RateLimit-Remaining` to know when you're approaching the limit
2. **Implement exponential backoff** - When receiving 429 errors, wait progressively longer between retries
3. **Cache responses** - Store frequently-accessed data to reduce API calls
4. **Batch operations** - Use comprehensive update endpoints (PUT) instead of multiple PATCH requests
5. **Use webhooks** - Subscribe to events instead of polling for status changes
6. **Respect Retry-After** - Always wait the specified time before retrying

#### Example: Rate Limit Handling

```javascript theme={null}
async function makeApiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check rate limit headers
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    
    if (remaining < 10) {
      console.warn(`Rate limit warning: ${remaining} requests remaining`);
    }
    
    // Handle rate limit exceeded
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      
      if (attempt < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
const response = await makeApiRequest(
  'https://api.firma.dev/functions/v1/signing-request-api/templates',
  {
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    }
  }
);
```

## For Very High Volume Applications

Rate limits may be raised by request to Support. Please contact support if you believe you need a higher rate limit for your use case.


# Replit
Source: https://docs.firma.dev/guides/replit-integration

Add legally binding e-signatures to any Replit app using backend routes, Replit Secrets, and Replit Agent.

Firma lets you add legally binding e-signatures to any Replit application. Use Replit's Node.js or Python backend to call the Firma API, manage templates, send signing requests, and track completions via webhooks.

This guide covers three integration paths:

1. **Node.js + Express** — Add a backend route that calls the Firma REST API. Best when your app is already using JavaScript or TypeScript.
2. **Python + Flask** — Same concepts, Python syntax. Best when your app is already using Python.
3. **Replit Agent prompt** — Let Replit Agent wire up the Firma integration for you from a natural language prompt. Works for any app.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Replit account (the free Starter plan includes daily Agent credits; deployments require a paid plan)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Path 1: Node.js + Express

You add a backend route that calls the Firma REST API using your API key stored as a Replit Secret.

### Step 1: Store your API key as a Replit Secret

1. Open your Repl
2. Open the **Secrets** tool from the left tool dock (or search for "Secrets" using the search bar)
3. Click **New Secret**
4. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value

> [!WARNING]
>
> Never expose your API key in frontend code. Always call the Firma API from a backend route where secrets are kept secure.

> [!NOTE]
>
> Replit workspace secrets do not automatically carry over to deployments. After you add a secret in the workspace, also add it in the **Publish** pane under its own Secrets section before publishing. This is the single most common reason a Firma integration works in development but fails in production.

### Step 2: Create a backend route to send signing requests

Add a route to your Express server. This example uses the `create-and-send` endpoint to create a signing request from a template and send it in a single API call:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

app.post("/api/send-signing-request", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } = req.body;

  try {
    const response = await fetch(`${FIRMA_API}/signing-requests/create-and-send`, {
      method: "POST",
      headers: {
        Authorization: process.env.FIRMA_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    });

    const data = await response.json();

    if (!response.ok) {
      return res.status(response.status).json({ error: data });
    }

    res.json({
      signing_request_id: data.id,
      status: "sent",
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, "0.0.0.0", () => {
  console.log(`Server running on port ${PORT}`);
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 3: Connect the route to your app UI

Call the backend route from your frontend:

```javascript theme={null}
async function sendContract() {
  const response = await fetch("/api/send-signing-request", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "NDA for Alice Johnson",
      template_id: "your-template-id",
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const result = await response.json();
  console.log("Signing request sent:", result.signing_request_id);
}
```

If you are building with Replit Agent, you can also describe the flow in chat and let Agent wire it up, for example: *"When the user clicks the Send Contract button, call /api/send-signing-request with the template ID, signer email, and name from the form."*

### Webhook integration

To track when documents are signed, add a second route to receive Firma webhook events.

1. Add a `POST /api/firma-webhook` route to your Express server
2. Publish your Repl so it has a public HTTPS URL (for example `https://your-app.replit.app`)
3. In the Firma dashboard under **Settings → Webhooks**, register a webhook pointing to `https://your-app.replit.app/api/firma-webhook`
4. Firma sends events for key state changes — see the [webhooks guide](/guides/webhooks) for all event types

```javascript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database or trigger the next step in your workflow.
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
});
```

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

> [!NOTE]
>
> Webhook endpoints only work on published Repls, not the development URL. Publish your app via **Autoscale** or **Reserved VM** before registering the webhook. Static deployments do not support backend routes.

## Path 2: Python + Flask

Same integration, Python syntax. Useful if your Repl is already running Flask or FastAPI.

### Step 1: Store your API key

Same as Path 1: open the **Secrets** tool, add `FIRMA_API_KEY` with your Firma API key as the value.

### Step 2: Create a Flask route

```python theme={null}
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api"

@app.route("/api/send-signing-request", methods=["POST"])
def send_signing_request():
    body = request.get_json()
    template_id = body.get("template_id")
    name = body.get("name")
    signer_email = body.get("signer_email")
    signer_first_name = body.get("signer_first_name")
    signer_last_name = body.get("signer_last_name")

    response = requests.post(
        f"{FIRMA_API}/signing-requests/create-and-send",
        headers={
            "Authorization": os.environ["FIRMA_API_KEY"],
            "Content-Type": "application/json",
        },
        json={
            "name": name,
            "template_id": template_id,
            "recipients": [
                {
                    "first_name": signer_first_name,
                    "last_name": signer_last_name,
                    "email": signer_email,
                    "designation": "Signer",
                    "order": 1,
                }
            ],
        },
    )

    data = response.json()

    if not response.ok:
        return jsonify({"error": data}), response.status_code

    return jsonify({
        "signing_request_id": data["id"],
        "status": "sent",
    })


@app.route("/api/firma-webhook", methods=["POST"])
def firma_webhook():
    payload = request.get_json()
    event_type = payload.get("type")
    data = payload.get("data", {})

    if event_type == "signing_request.completed":
        signing_request_id = data["signing_request"]["id"]
        # Update your database or trigger the next step in your workflow

    if event_type == "signing_request.recipient.signed":
        recipient_email = data.get("recipient", {}).get("email")
        # Handle individual recipient signing

    return jsonify({"received": True})


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
```

Call this from your frontend exactly like the Node.js version. The request and response shapes are identical.

## Path 3: Build the integration with Replit Agent

If you are using Replit Agent to generate your app, you can skip writing the boilerplate yourself. Give Agent a prompt like this:

```text theme={null}
Add an e-signature feature to this app using the Firma API.

Create a POST /api/send-signing-request route that:
- Reads the API key from process.env.FIRMA_API_KEY
- Accepts name, template_id, signer_email, signer_first_name, signer_last_name in the request body
- Calls POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send
- Sends the Authorization header as the raw API key (no Bearer prefix needed)
- Includes the "name" field in the request body (it is required)
- Returns the signing_request_id

Also create a POST /api/firma-webhook route that handles signing_request.completed events.

Add a "Send for signature" button to the UI that calls the route.
```

Agent will scaffold the route, wire it to the UI, and prompt you to add `FIRMA_API_KEY` to Secrets. For accurate API details during generation, connect the Firma Docs MCP server (see below), and Agent will pull the latest endpoint schemas directly from the Firma docs.

## Embedded signing

For apps where signers complete documents directly in your UI instead of a separate Firma page, embed the signing experience in an iframe. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Load the signer URL in your Replit app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma provides a [Docs MCP server](/guides/mcp) you can connect to Replit Agent. Once connected, Agent can search the Firma docs while generating code, so it writes integrations with the correct endpoints, parameters, and auth headers instead of guessing.

To set it up:

1. Go to the **Integrations** page in Replit
2. Scroll to **MCP Servers for Replit Agent** and click **Add MCP server**
3. Give it a name like `firma-docs`
4. Enter the server URL: `https://docs.firma.dev/mcp`
5. Click **Test & Save**

Agent will now pull Firma documentation automatically when you ask it to build anything that touches e-signatures.

## Multi-tenant SaaS: Customer Workspaces

If you are building a multi-tenant SaaS app on Replit where each of your customers needs their own isolated signing environment, use Firma [Customer Workspaces](/guides/creating-workspaces). Each customer gets a private workspace with their own templates, signing requests, and usage tracking, with no data bleed between tenants. Create a new workspace from your backend when a customer signs up, and store their workspace ID and API key alongside the rest of their tenant record.

## Next steps

* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [API reference](/api-reference) — full endpoint documentation


# Rork
Source: https://docs.firma.dev/guides/rork-integration

Add legally binding e-signatures to any Rork mobile app using serverless functions and the Firma REST API.

Firma lets you add legally binding e-signatures to any mobile application built with [Rork](https://rork.app). Since Rork generates React Native (Expo) apps, you can call the Firma API from a lightweight backend and render the signing experience in a WebView within your mobile app.

This guide covers the recommended integration path: a serverless backend function that calls the Firma REST API, with a React Native WebView for embedded signing.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Rork](https://rork.app)-generated mobile app (React Native / Expo)
* At least one Firma template with signing fields configured
* A backend for secure API calls. Options include Rork Backend, Supabase Edge Functions, Vercel Serverless Functions, or any Node.js/Python server

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Set up your backend

Rork apps run on the client, so you need a server-side layer to keep your API key secret. This example uses a Supabase Edge Function, but the same logic applies to any backend.

Create the Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Store your Firma API key as a secret:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

> [!WARNING]
>
> Never call the Firma API directly from your React Native app. The API key would be exposed in the app bundle and could be extracted by anyone who downloads your app.

Then replace the generated `index.ts` with the following:

```typescript theme={null}
// supabase/functions/send-signing-request/index.ts
const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { template_id, signer_email, signer_first_name, signer_last_name } =
      await req.json();

    const apiKey = Deno.env.get("FIRMA_API_KEY");
    if (!apiKey) {
      return new Response(
        JSON.stringify({ error: "FIRMA_API_KEY not configured" }),
        { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    const response = await fetch(
      `${FIRMA_API}/signing-requests/create-and-send`,
      {
        method: "POST",
        headers: {
          Authorization: apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          name: "Contract for " + signer_first_name + " " + signer_last_name,
          template_id,
          recipients: [
            {
              first_name: signer_first_name,
              last_name: signer_last_name,
              email: signer_email,
              designation: "Signer",
              order: 1,
            },
          ],
        }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      return new Response(
        JSON.stringify({ error: data }),
        { status: response.status, headers: { ...corsHeaders, "Content-Type": "application/json" } }
      );
    }

    return new Response(
      JSON.stringify({
        signing_request_id: data.id,
        first_signer: data.first_signer,
        status: "sent",
      }),
      { headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } }
    );
  }
});
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Deploy the function:

```bash theme={null}
supabase functions deploy send-signing-request --no-verify-jwt
```

## Step 2: Call the backend from React Native

From your Rork app, POST to your Edge Function when the user triggers the signing flow:

```typescript theme={null}
const BACKEND_URL = "https://<your-project-ref>.supabase.co/functions/v1";

async function sendSigningRequest(templateId: string) {
  const response = await fetch(`${BACKEND_URL}/send-signing-request`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      template_id: templateId,
      signer_email: "alice@example.com",
      signer_first_name: "Alice",
      signer_last_name: "Johnson",
    }),
  });

  const data = await response.json();
  console.log(data);
  // data.signing_request_id - the signing request ID
  // data.first_signer.id - the signing_request_user_id for embedded signing
  // data.first_signer.signing_link - direct link to the signing page
  return data;
}
```

## Step 3: Embedded signing in a WebView

For mobile apps, the signing experience renders inside a WebView instead of an iframe. Install `react-native-webview`:

```bash theme={null}
npx expo install react-native-webview
```

Then create a signing screen component. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Use either to build the signing URL:

```typescript theme={null}
import React from "react";
import { View, StyleSheet, ActivityIndicator } from "react-native";
import { WebView } from "react-native-webview";

interface EmbeddedSigningProps {
  signingRequestUserId: string;
}

export function EmbeddedSigning({ signingRequestUserId }: EmbeddedSigningProps) {
  return (
    <View style={styles.container}>
      <WebView
        source={{
          uri: `https://app.firma.dev/signing/${signingRequestUserId}`,
        }}
        style={styles.webview}
        startInLoadingState
        renderLoading={() => (
          <ActivityIndicator
            style={styles.loading}
            size="large"
            color="#0066FF"
          />
        )}
        javaScriptEnabled
        domStorageEnabled
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
  loading: {
    position: "absolute",
    top: "50%",
    left: "50%",
  },
});
```

Pass `first_signer.id` from the response in Step 2 as the `signingRequestUserId` prop. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Webhook integration

To track when documents are signed, add a webhook Edge Function and register it in the Firma dashboard.

```typescript theme={null}
// supabase/functions/firma-webhook/index.ts
Deno.serve(async (req) => {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a push notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" },
  });
});
```

Deploy and register the webhook:

1. Deploy the function: `supabase functions deploy firma-webhook --no-verify-jwt`
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-project-ref>.supabase.co/functions/v1/firma-webhook`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that can be connected to AI coding tools. When connected, AI assistants search Firma documentation while generating code so they use accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Salesforce
Source: https://docs.firma.dev/guides/salesforce-integration

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce.

Add legally binding e-signatures to any Salesforce org using Flow, Apex, or Agentforce. Send signing requests off a record update, embed signing in Lightning, and route webhook events back to Salesforce records.

This guide covers three integration paths:

1. **Flow with External Services** — No-code. Register Firma's OpenAPI spec once, then invoke `Create and send signing request` from any Flow. Best for admins.
2. **Apex with Named Credentials** — Code. Call Firma directly from Apex classes, Flow Actions, or LWC controllers. Best for developers who want full control.
3. **Agentforce action** — Expose Firma as an Action on an Agentforce agent so it can send signing requests in response to a user prompt or a trigger.

All three paths share the same Named Credential, so set that up first.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Salesforce org (Enterprise, Unlimited, or Developer edition) with permission to create Named Credentials and External Services
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value. Do not prefix it with `Bearer`. This differs from many other APIs.

## Step 0: Store the Firma API key as a Named Credential

Named Credentials are Salesforce's secure pattern for storing endpoint URLs and auth headers. Every other section in this guide references it.

1. In Setup, search for **Named Credentials** and open the page
2. Under **External Credentials**, click **New**:
   * Label: `Firma`
   * Name: `Firma`
   * Authentication Protocol: `Custom`
3. Click into the new External Credential, scroll to **Principals**, and click **New**:
   * Parameter Name: `Default`
   * Sequence Number: `1`
   * Identity Type: `Named Principal`
   * Authentication Parameters: add one parameter
     * Name: `ApiKey`
     * Value: your Firma API key
4. Scroll to **Custom Headers** and add one:
   * Name: `Authorization`
   * Value: `{!$Credential.Firma.ApiKey}`
5. Back under **Named Credentials**, click **New**:
   * Label: `Firma API`
   * Name: `Firma_API`
   * URL: `https://api.firma.dev/functions/v1/signing-request-api`
   * External Credential: `Firma`
   * Allowed Namespaces: leave default
6. Save

> [!WARNING]
>
> Never hardcode the API key in Apex, Flow, or a Custom Setting. Always reference it through the Named Credential so it stays encrypted at rest and rotation only requires editing one record.

## Path 1: Flow with External Services

The no-code path. You import Firma's OpenAPI spec once, and the actions become available as invocable steps in any Flow.

### Step 1: Register Firma as an External Service

1. In Setup, search for **External Services** and click **Add an External Service**
2. Choose **From API Specification**, then **Save and Next**
3. Configure:
   * External Service Name: `Firma`
   * Select a Named Credential: `Firma_API`
   * Service Schema: `Upload from Local` or paste the JSON
4. Paste the Firma OpenAPI spec from `https://docs.firma.dev/api-reference/v01.26.00/openapi-v01.26.00.json`
5. Click **Save and Next**
6. Select the operations you want available in Flow. Common picks:
   * `POST /signing-requests/create-and-send`
   * `POST /signing-requests`
   * `POST /signing-requests/{id}/send`
   * `GET /signing-requests/{id}`
   * `GET /templates`
7. Click **Save and Next**, then **Finish**

> [!NOTE]
>
> Check the [Firma API changelog](/guides/api-changelog) for the latest spec URL. Salesforce caches the spec at registration time, so re-register the External Service whenever you want new endpoints.

### Step 2: Build the Flow

1. In Setup, open **Flows** and create a new Flow (Record-Triggered is the most common)
2. Choose your trigger object (Opportunity, Contract, Quote, or a custom object) and the condition that should send a signing request (e.g., `StageName` equals `Closed Won`)
3. Add an **Action** element
4. Search for `Firma` and pick `Create and send signing request`
5. Map the inputs:
   * `template_id`: a Custom Metadata value, a record field, or a hardcoded template ID
   * `recipients`: build a collection of recipient records. Required fields are `first_name` and `email`. Optional fields include `last_name`, `designation` (defaults to `Signer`), `order`, `company`, `title`, `phone_number`, and address fields. The easiest way is an **Assignment** element that builds the collection from the triggering record's contact fields.
6. Save and activate

When the trigger fires, Salesforce calls Firma over the Named Credential and Firma sends the document to the signer.

## Path 2: Apex with Named Credentials

For developers who want full control, call Firma directly from Apex. Use the Named Credential as the endpoint base so the API key stays encrypted.

```java theme={null}
public with sharing class FirmaService {

    private static final String FIRMA_BASE = 'callout:Firma_API';

    public class Recipient {
        public String first_name;
        public String last_name;
        public String email;
        public String designation;
        public Integer order;
    }

    public static String createAndSend(String templateId, Recipient signer) {
        signer.designation = 'Signer';
        signer.order = 1;

        Map<String, Object> body = new Map<String, Object>{
            'template_id' => templateId,
            'recipients' => new List<Recipient>{ signer }
        };

        HttpRequest req = new HttpRequest();
        req.setEndpoint(FIRMA_BASE + '/signing-requests/create-and-send');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setBody(JSON.serialize(body));

        Http http = new Http();
        HttpResponse res = http.send(req);

        if (res.getStatusCode() >= 300) {
            throw new CalloutException('Firma error: ' + res.getBody());
        }

        Map<String, Object> data =
            (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        return (String) data.get('id');
    }
}
```

The `callout:Firma_API` prefix tells Salesforce to use the Named Credential, which injects the `Authorization` header automatically. No API key appears in code, in logs, or in serialized request inspection.

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and emails it to recipients in one call. If you need an Apex-controlled review step, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

Expose the Apex method as an Invocable Action so Flow can call it:

```java theme={null}
public with sharing class FirmaInvocable {

    public class Input {
        @InvocableVariable(required=true) public String templateId;
        @InvocableVariable(required=true) public String firstName;
        @InvocableVariable(required=true) public String lastName;
        @InvocableVariable(required=true) public String email;
    }

    public class Output {
        @InvocableVariable public String signingRequestId;
    }

    @InvocableMethod(label='Send Firma signing request')
    public static List<Output> send(List<Input> inputs) {
        List<Output> results = new List<Output>();
        for (Input i : inputs) {
            FirmaService.Recipient r = new FirmaService.Recipient();
            r.first_name = i.firstName;
            r.last_name = i.lastName;
            r.email = i.email;
            String id = FirmaService.createAndSend(i.templateId, r);
            Output o = new Output();
            o.signingRequestId = id;
            results.add(o);
        }
        return results;
    }
}
```

## Path 3: Agentforce action

To let an Agentforce agent send signing requests in response to a prompt ("send the standard NDA to [alice@example.com](mailto:alice@example.com)"), wrap one of the above as an Agent Action.

1. In Setup, open **Agentforce Builder** and pick the agent you want to extend
2. Open the relevant **Topic** (e.g., `Contract Lifecycle`)
3. Click **New Action** and choose **Flow** or **Apex**
   * **Flow**: pick a screen Flow or autolaunched Flow that wraps the `Firma.Create and send signing request` External Services action
   * **Apex**: pick the `FirmaInvocable.send` method
4. Define inputs the agent will collect from the conversation: template, signer name, signer email
5. Add the action to the Topic and publish

> [!WARNING]
>
> Use Agentforce's confirmation prompt before any send action so the agent reads back the template name and signer details before triggering Firma. Outbound signing requests reach external parties; a confirmation step is worth the extra turn.

## Webhook integration: react when documents are signed

Receive Firma webhooks into Salesforce by exposing an Apex REST endpoint, then update the originating record (Opportunity, Contract, custom object) when the signing request completes.

### Step 1: Create the Apex REST endpoint

```java theme={null}
@RestResource(urlMapping='/firma-webhook')
global with sharing class FirmaWebhook {

    @HttpPost
    global static void receive() {
        RestRequest req = RestContext.request;
        Map<String, Object> payload =
            (Map<String, Object>) JSON.deserializeUntyped(
                req.requestBody.toString()
            );

        String eventType = (String) payload.get('type');
        Map<String, Object> data =
            (Map<String, Object>) payload.get('data');

        if (eventType == 'signing_request.completed') {
            Map<String, Object> sr =
                (Map<String, Object>) data.get('signing_request');
            String signingRequestId = (String) sr.get('id');

            List<Opportunity> opps = [
                SELECT Id FROM Opportunity
                WHERE Firma_Signing_Request_Id__c = :signingRequestId
                LIMIT 1
            ];
            if (!opps.isEmpty()) {
                opps[0].StageName = 'Signed';
                update opps[0];
            }
        }

        RestContext.response.statusCode = 200;
    }
}
```

### Step 2: Verify the webhook signature

Firma signs every webhook payload with HMAC-SHA256. Always verify the signature in production to reject spoofed payloads. Your webhook secret is available in **Settings > Webhooks** in the Firma dashboard.

```java theme={null}
private static Boolean verifySignature(
    String payload, String signatureHeader, String secret
) {
    Blob hmac = Crypto.generateMac(
        'HmacSHA256',
        Blob.valueOf(payload),
        Blob.valueOf(secret)
    );
    String expected = EncodingUtil.convertToHex(hmac);
    return expected.equalsIgnoreCase(signatureHeader);
}
```

Call this at the top of the `receive()` method before processing:

```java theme={null}
String signature = RestContext.request.headers.get('x-firma-signature');
String body = RestContext.request.requestBody.toString();
String secret = '{!$Credential.Firma_Webhook.Secret}'; // or a Custom Metadata value

if (!verifySignature(body, signature, secret)) {
    RestContext.response.statusCode = 401;
    return;
}
```

### Step 3: Expose the endpoint publicly

Firma's webhook calls aren't authenticated as a Salesforce user, so expose the endpoint through an **Experience Cloud Site**. Create a site (or use an existing one), then grant the site's guest user profile permission to execute the `FirmaWebhook` Apex class. See [Salesforce: Allow Guest Users to Access Apex REST](https://help.salesforce.com/s/articleView?id=sf.networks_guest_user_access_apex_rest.htm) for the full setup steps.

### Step 4: Register the webhook in Firma

1. In the Firma dashboard, go to **Settings > Webhooks**
2. Add a new webhook pointing at `https://<your-site-domain>/services/apexrest/firma-webhook`
3. Subscribe to the events you care about (`signing_request.completed`, `signing_request.recipient.declined`, `signing_request.expired`)

See the [webhooks guide](/guides/webhooks) for all event types and payload shapes.

## Embedded signing in Lightning

If you want signers to complete documents inside a Lightning page, use a Lightning Web Component that embeds the Firma signing UI. After a successful create-and-send call, read the signer ID from the response and pass it to the LWC:

```html theme={null}
<template>
  <iframe
    src={signingUrl}
    style="width:100%;height:900px;border:0;"
    allow="camera;microphone;clipboard-write"
    title="Document Signing"
  ></iframe>
</template>
```

```javascript theme={null}
import { LightningElement, api } from 'lwc';

export default class FirmaSigning extends LightningElement {
  @api signingRequestUserId;

  get signingUrl() {
    return `https://app.firma.dev/signing/${this.signingRequestUserId}`;
  }
}
```

Add `https://app.firma.dev` to your CSP Trusted Sites so the iframe loads. See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## For ISVs and AppExchange partners: multi-org signing

If you're building an AppExchange app that needs e-signatures for each of your customer orgs, use [Firma Customer Workspaces](/guides/creating-workspaces). Each customer org gets its own isolated Firma workspace with separate templates, usage tracking, and audit trail. Provision a workspace per org at install time, store the workspace API key in a Protected Custom Setting on that org, and reference it from the Named Credential. No data bleed between customers.

## MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) at `https://docs.firma.dev/mcp`. Connect it to Claude, Cursor, or any MCP-aware AI tool while you're writing Apex or building Flows, and the assistant can answer accurate API questions from Firma's docs. This is for the build experience and does not affect your deployed integration.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Security & Compliance
Source: https://docs.firma.dev/guides/security

Where Firma's infrastructure runs, how data is protected in transit and at rest, current compliance status, and how to report a security issue.

> [!NOTE]
>
> This page covers Firma's technical and organizational security posture. For the legal standing of Firma's electronic signatures under eIDAS, ESIGN, and UETA, see [Legal Validity & eIDAS Compliance](/guides/legal-validity).

**Quick answer:** Firma's infrastructure runs entirely in the EU, with encryption in transit and at rest, row-level access control on every database table, and a signing process backed by a full audit trail. Firma's security practices align with SOC 2 and ISO 27001 frameworks. Firma does not run a formal bug bounty program. Security reports are welcomed and acted on. Details below.

## Infrastructure overview

Firma's platform is built on a small set of managed providers, each running in the EU:

| Component | Provider | Purpose |
| - | - | - |
| Database, Auth, Storage, Edge Functions | Supabase | Primary application data, authentication, file storage, and serverless request handling |
| Signing API, certificate generation, AI classification proxy | AWS Lambda | Externally-facing signing API, completion-certificate PDF rendering, internal classification |
| Email delivery | Resend (on Amazon SES) | Sends signing invitations, reminders, and completion notifications to signers |
| Digital signature sealing | DSS (Digital Signature Service) | Applies the PAdES cryptographic seal to completed documents |

There's no self-managed server fleet - every component above is a managed cloud service, so patching, network isolation, and physical security are handled by Supabase and AWS's own security programs, not by Firma's own hardware.

## Data residency

All Firma infrastructure runs in EU data center regions, with no fallback or replication outside the EU:

* **Supabase (database, storage, edge functions):** `eu-west-3` - Paris, France
* **AWS Lambda (signing API, certificate generation):** `eu-west-3` - Paris, France
* **DSS (digital signature sealing):** `eu-north-1` - Stockholm, Sweden
* **Resend / Amazon SES (email delivery):** EU region - signer-facing emails (invitations, reminders) transit through Resend's infrastructure

Signing request documents, signer data, and account data are stored and processed exclusively within these regions. If your organization has a data residency requirement that specifies the EU, Firma's default deployment already satisfies it - there's no separate "EU region" tier to opt into.

## Encryption

**In transit:** All communication with Firma - the dashboard, the signing pages, the API, and every internal service-to-service call shown in Firma's [architecture overview](/guides/legal-validity) - is over HTTPS with TLS 1.2 or higher. Outbound webhooks are additionally signed with HMAC-SHA256 so the payload's integrity and origin can be verified independently of transport-layer security; see [Webhooks](/guides/webhooks#security-signature-verification-required). For the full list of Firma's services and how they communicate, see [Multi-Tenant Architecture](/guides/multi-tenant).

**At rest:** Database storage (Postgres) and file storage (signed documents, templates, certificates) are encrypted at rest with AES-256, using Supabase's and AWS's default encryption for their respective services. This is provider-managed encryption at the storage layer, not an application-level encryption scheme Firma implements itself.

## Authentication and access control

* **User authentication** is handled by Supabase Auth, supporting email/password and OAuth sign-in.
* **Passkey (WebAuthn) authentication** is available as an alternative to passwords.
* **Row-Level Security (RLS)** is enabled on every database table containing tenant data. Access to a row is enforced at the database layer based on the requesting user's company and workspace membership - not just at the application layer - so a bug in application code can't by itself expose one tenant's data to another.
* **API access** uses per-workspace API keys with rate limiting, independent of dashboard session authentication. See [Authentication](/guides/authentication).
* **Signing-time access** for recipients uses a unique per-signer link (valid until the signing request expires - default 7 days). An optional one-time-passcode (OTP) verification step can be enabled per workspace or per signing request to require a code-based identity check before granting a session.

## Compliance status

Firma's security practices align with SOC 2 and ISO 27001 frameworks:

Firma is not HDS certified. If your use case involves regulated French health data, do not treat the general security controls on this page as HDS certification.

* **SOC 2 alignment.** Firma's infrastructure, access controls, and data handling practices are designed around the SOC 2 Trust Services Criteria (security, availability, confidentiality).
* **ISO 27001 alignment.** Firma follows an information security management approach consistent with ISO 27001 controls.
* **No formal penetration test report available for distribution.** Security review happens on an ongoing basis (see [Responsible disclosure](#responsible-disclosure) below), but there is no third-party pen test report currently available to share with prospective customers.

> [!NOTE]
>
> For the legal-validity side of compliance - eIDAS signature tiers, ESIGN/UETA, and country-specific rules - see [Legal Validity & eIDAS Compliance](/guides/legal-validity). That page also covers SOC 2/ISO 27001 alignment in the context of signature legal weight.

## Data Processing Agreement (DPA)

Firma's [Data Processing Agreement](https://firma.dev/legal/data-processing-agreement) is published and applies to all customers. It is incorporated into the Terms and Conditions by reference, so there is nothing to request or sign separately. It names Firma's sub-processors, sets out the international transfer safeguards (EU Standard Contractual Clauses), and covers retention and deletion on termination.

## Responsible disclosure

Firma does not run a formal, published bug bounty program. That doesn't mean security reports go unheard - they're read, triaged, and acted on.

If you believe you've found a security vulnerability in Firma:

* Email [security@firma.dev](mailto:security@firma.dev) with a description of the issue, steps to reproduce, and any relevant request/response details.
* Please report privately rather than disclosing publicly first, and avoid testing against other customers' data or accounts.
* Firma does not currently commit to a fixed response-time SLA for security reports, but reports are prioritized above routine feature work when a real vulnerability is confirmed.

Firma reviews and responds to security reports on an ongoing basis, and confirmed issues have led to fixes; in at least one case, a reporter received a discretionary bounty payment outside of any formal program. This is handled case by case rather than through a published bounty schedule.

## Related guides

* [Legal Validity & eIDAS Compliance](/guides/legal-validity) - signature tiers, admissibility, and SOC 2/ISO 27001 alignment in a legal context
* [Audit Trail](/guides/audit-trail) - the full event log behind every signing request
* [Webhooks](/guides/webhooks#security-signature-verification-required) - HMAC signature verification for outbound events
* [Authentication](/guides/authentication) - API key and session authentication details


# Sending a signing request
Source: https://docs.firma.dev/guides/sending-signing-request

How to create and send signing requests to recipients.

# Sending a signing request

This guide covers creating a signing request, attaching a template or document, and inviting recipients to sign.

## Create vs. create-and-send

> [!WARNING]
>
> `POST /signing-requests` creates a **draft only** - it never sends an email, no matter what settings you pass. To notify recipients immediately, use `POST /signing-requests/create-and-send` instead, or call `.../send` on the draft afterward. This is the most common cause of "I created a signing request but nothing was sent" reports.

Firma exposes two ways to start a signing request, and picking the wrong one is the most common integration mistake:

| | `POST /signing-requests` (create) | `POST /signing-requests/create-and-send` |
| :- | :- | :- |
| Result | A **draft** (`status: "not_sent"`). Nothing is sent. | The request is created **and** sent, atomically, in one call. |
| Recipients notified? | Never - regardless of `send_signing_email` or any other setting. | By default, yes. See `send_signing_email` below. |
| Credit charged / `sent_on` set? | No | Yes, immediately. |
| Still editable via PATCH/PUT? | Yes, until you call `/send` | No - the request is already in a sent state. |
| Best for | A **draft-then-edit** workflow: build the request, adjust recipients or fields, have it reviewed internally, then send when ready. | A **fire-and-forget** call when you already have everything you need. |

Use [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) when your workflow needs a review or editing step before anything reaches a recipient. Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) when you want the request live and recipients notified in a single call.

### The `send_signing_email` flag

This flag lives in `settings.send_signing_email`, but it means something different depending on which endpoint you call:

| Endpoint | Effect of `send_signing_email: false` |
| :- | :- |
| `POST /signing-requests` (create) | None. This endpoint never sends an email on its own, so the flag is simply stored for later - it only takes effect once the draft is actually sent. |
| `POST /signing-requests/create-and-send` | The request is still created **and** sent: credit is charged, `sent_on` is set, the `signing_request.sent` webhook fires, and the signing link is live. Only the recipient notification **email** is suppressed. |

> [!WARNING]
>
> `send_signing_email: false` on `create-and-send` is **not** a silent draft - it's a fully sent, billed signing request with no email attached. Use it when you plan to deliver the signing link yourself (embedding it, or sending your own notification). If you want something you can still cancel or edit before it becomes final, use `create` (the draft endpoint) instead.

### The `allow_presigning_download` flag

Controls whether recipients can download the unsigned document before completing their part of the signing flow. It behaves the same on both endpoints:

* If you set it explicitly in `settings`, that value is stored on the signing request.
* If you omit it, it resolves at view/download time through an inheritance chain: signing request → workspace → company setting, defaulting to **disallowed** if none of those are set.
* When creating from a template and omitting it, the request inherits the template's own `allow_presigning_download` value.

> [!NOTE]
>
> The public OpenAPI schema for `create-and-send` doesn't currently list `allow_presigning_download` under its `settings` object, but the endpoint accepts and applies it identically to `POST /signing-requests`.

## Steps

1. Create or select a template
2. Create a signing request referencing the template
3. Add recipients with required information (first name, last name, email)
4. Optionally add form fields with percentage-based positioning
5. Send the request via email or embed the signing view

## Recipient Schema (Required Fields)

> [!NOTE]
>
> Recipients use `first_name` and `last_name` as separate fields. `last_name` is required for raw-document creation and optional for template-based requests; there is no single `name` field.

Each recipient must include:

* `first_name` (required) - Recipient's first name
* `last_name` (optional) - Recipient's last name (required only when creating via `POST /signing-requests` with a raw document)
* `email` (required) - Email address (`create` warns on invalid format; `create-and-send` and `/send` reject it)
* `designation` (required) - Role: `"Signer"`, `"CC"`, or `"Approver"`. Approvers review and approve the document (no signature) via the `approval_*` field types below
* `order` (optional) - Signing order for sequential workflows

Optional fields:

* `phone_number`, `street_address`, `city`, `state_province`, `postal_code`, `country`, `title`, `company`
* `custom_fields` - Object with custom key-value pairs

## Create a signing request from a template (API)

> Endpoint: POST /signing-requests

Example curl (create request from template):

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

Successful response (201) returns a `Document` resource including `id` (the signing\_request\_id) and `document_url` where appropriate.

## Create a signing request (server example) - Node (fetch)

```js theme={null}
const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/signing-requests', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contains id, document_url, recipients, etc.
}
```

## Create a signing request (server example) - Python (requests)

```py theme={null}
import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()
```

## Create a signing request from a document

Instead of using a template, you can create a signing request by uploading a PDF or DOCX document directly. Choose the method based on your file size:

> [!WARNING]
>
> Inline base64 (`document`) works for small files. Keep the body under about 5 MB; a request body over 6,291,456 bytes returns `413 REQUEST_TOO_LARGE`. If a document is anywhere near 5 MB, use the two-step upload flow (`document_id`) below instead.

**Small files (under 5MB)**

For documents under 5MB, include the base64-encoded file directly in the request body:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

**Large files (up to 50MB)**

For documents over 5MB, use the two-step upload flow:

**Step 1: Request an upload URL**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'
```

Response:

```json theme={null}
{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}
```

**Step 2: Upload the file**

```bash theme={null}
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf
```

**Step 3: Create the signing request**

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'
```

> [!NOTE]
>
> The upload URL expires after 1 hour and can only be used once. Each `document_id` can only be used in one signing request.

> [!WARNING]
>
> You must provide exactly one of `document`, `document_id`, `document_ids`, or `template_id`. They are mutually exclusive.

## Adding form fields (percentage-based positioning)

> [!WARNING]
>
> **Critical**: All field position coordinates (x, y, width, height) must be **percentages (0-100)** relative to page dimensions, not pixels. The `page_number` field is required.

> [!TIP]
>
> Want a field to show a value before the signer touches it - a fixed value you already know, or the recipient's own profile data? See the [Field Prefilling guide](/guides/field-prefilling). `variable_name` alone does **not** do this.

When creating a signing request directly (POST `/signing-requests`) or updating one, you can add form fields:

### Field positioning example

```json theme={null}
{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}
```

### Field types

* `signature` - Signature field
* `text` - Single-line text input
* `date` - Date picker
* `checkbox` - Checkbox
* `dropdown` - Dropdown selector (requires `dropdown_options`)
* `initial` - Initials field (also accepts `initials` as an alias)
* `approval_signature` - APPROVED stamp (Approver only)
* `approval_checkmark` - Approval checkmark (Approver only)
* `approval_date` - Approval date (Approver only)

> [!NOTE]
>
> The `approval_*` field types can only be assigned to a recipient whose `designation` is `"Approver"` (assigning one to a Signer returns a `400`). Their value is authored server-side when the approver completes their review, so you don't submit a value for them, and the approval stamp is rendered onto the completion certificate.

### Positioning guidelines

The coordinate system uses percentages for responsive scaling:

* `x`: 0 (left edge) to 100 (right edge)
* `y`: 0 (top edge) to 100 (bottom edge)
* `width`: percentage of page width (e.g., 30 = 30% width)
* `height`: percentage of page height (e.g., 8 = 8% height)

> [!TIP]
>
> For a US Letter page (8.5" × 11"), use these rough conversions:
>
> * 1 inch ≈ 11.76% width
> * 1 inch ≈ 9.09% height

## Updating signing requests

Before a signing request is sent, you can update its details using the API. The API provides two methods:

> [!WARNING]
>
> **Cannot update after sending**: Once a signing request is sent, it cannot be modified. Updates only work for requests with status `not_sent`.

### Comprehensive update (PUT)

Use [`comprehensive-update-signing-request`](../api-reference/v01.15.00/signing-requests/comprehensive-update-signing-request) for complex updates involving multiple sections.

**When to use**:

* Updating multiple recipients at once
* Deleting recipients (with field reassignment/deletion)
* Updating fields and reminders together
* Making coordinated changes across multiple sections

**Structure**: All sections are optional, but at least one must be provided:

* `signing_request_properties` - Update name, description, document, expiration, settings
* `recipients` - Upsert recipients (include id to update, omit to create)
* `deleted_recipients` - Delete recipients with `field_action` (delete or reassign fields)
* `fields` - Upsert fields (include id to update, omit to create)
* `reminders` - Upsert reminders (include id to update, omit to create)

**Requirements**:

* ✅ Can update multiple sections in one request
* ✅ Supports recipient deletion with field handling
* ✅ Only works before the request is sent

**Example** (Node.js):

```javascript theme={null}
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Include id to update existing
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omit id to create new recipient
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    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'
      }
    ]
  })
});

const updatedRequest = await response.json();
```

### Partial update (PATCH)

Use [`partially-update-signing-request`](../api-reference/v01.15.00/signing-requests/partially-update-signing-request) when updating specific properties or a single recipient.

**When to use**:

* Updating name, description, or settings
* Adding or updating one recipient at a time
* Making targeted changes without affecting other data

**Important**: Cannot update both properties AND a recipient in the same request. Choose one:

* Update properties only (name, description, document, expiration\_hours, settings)
* OR update/create a single recipient

**Benefits**:

* ✅ Only send the fields you want to change
* ✅ More efficient for small changes
* ✅ Other fields remain unchanged
* ✅ Safer for concurrent edits

**Example** (Node.js):

```javascript theme={null}
// Update a single recipient
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Include id to update existing recipient
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();
```

**Example** (Python):

```python theme={null}
import requests
import os

# Update only properties (name and expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()
```

### Choosing between PUT and PATCH

| Scenario | Use | Reason |
| - | - | - |
| Complete signing request rebuild | PUT | Full replacement with all sections (properties, recipients, fields, reminders) |
| Update name or settings only | PATCH | More efficient, preserves recipients and fields |
| Add/update one recipient | PATCH | Single recipient mode, other recipients unchanged |
| Update multiple recipients | PUT | Can upsert multiple recipients in one request |
| Delete recipients with field reassignment | PUT | Supports deleted\_recipients with field\_action |
| Change document and all fields | PUT | Major structural changes |
| Update custom fields | PATCH | Preserves core signing request |
| Replace all recipients | PUT | Clean slate approach |

> [!WARNING]
>
> **Important**: Both update methods only work **before** the signing request is sent. Once sent, the signing request becomes immutable to prevent tampering with active signature workflows.

**Best practices**:

* Update signing requests before calling `/send`
* Validate recipient data before updating
* Use PATCH for incremental changes
* Implement retry logic with exponential backoff

***

## Sending (email invites)

Once you have a signing request ID (and have made any necessary updates), call POST `/signing-requests/{signing_request_id}/send` to send emails to all recipients.

### Example

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'
```

> [!NOTE]
>
> The `/send` endpoint validates that all recipients have required information (`first_name` and `email` - `last_name` is optional) and that any prefilled fields have the corresponding recipient data present.

***

## Embedding the signing view

To embed the signing experience in your own app, fetch the recipient's `id` from `GET /signing-requests/{id}/users` and build the signing URL:

```
https://app.firma.dev/signing/{recipient_id}
```

Render this URL in an iframe. For the complete embed setup - including postMessage events, iframe sizing, and camera/clipboard permissions - see the [Embeddable Signing guide](/guides/embeddable-signing).

## Edge cases & tips

* **Signing order**: Ensure recipients have sequential `order` values (1, 2, 3...) for sequential signing workflows
* **Audit trail**: Download the audit trail via GET `/signing-requests/{id}/audit` to see all user actions
* **Download completed PDF**: Use GET `/signing-requests/{id}/download` after completion
* **Webhooks**: Subscribe to events like `signing_request.completed` instead of polling (see [Webhooks guide](/guides/webhooks))

## Next steps

* [Prefill fields with recipient or static data](/guides/field-prefilling) before you send
* [Set up webhooks](/guides/webhooks) to receive real-time event notifications
* [Add automated reminders](../api-reference/v01.15.00/signing-requests/get-signing-request-reminders) for pending recipients
* [Embed the template editor](/guides/embeddable-template-editor) with JWT authentication (120 req/min)
* [Configure workspace settings](/guides/workspace-settings) for custom email templates (100-200 req/min)
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for secure embedded workflows

> [!TIP]
>
> * For sequential signing workflows with multiple signers, ensure each recipient has a sequential `order` value (1, 2, 3...).
> * For audit and compliance, download the final PDF via GET /signing-requests/signing\_request\_id/download after completion.
> * Use webhooks (see [Webhooks Guide](/guides/webhooks)) to react to signing events instead of polling.


# Signing Request Patterns
Source: https://docs.firma.dev/guides/signing-patterns

Common multi-signer workflows - sequential, parallel, dynamic recipients, and signer-plus-approver - with the API calls and webhook logic each one needs.

This guide covers the recurring shapes that signing workflows take: multiple signers who go in order, signers who don't need an order, a second signer whose identity isn't known until the first one acts, and a signer who also has to approve. Each pattern below is a variation on [creating and sending a signing request](/guides/sending-signing-request), so read that guide first if you haven't already.

## Choosing a pattern

| Scenario | Pattern |
| :- | :- |
| Two or more signers, all emails known before you send | [Sequential signing](#pattern-sequential-signing-known-recipients) |
| Signer 2's email is only known after signer 1 finishes | [Dynamic second signer](#pattern-dynamic-second-signer) |
| Multiple signers, none waiting on each other | [Parallel signing](#pattern-parallel-signing) |
| One person needs to both sign and approve | [Signer + approver](#pattern-signer-and-approver) |

## Pattern: Sequential signing, known recipients

Use this when every recipient's email is known at send time and later signers should only be notified once earlier ones finish. This is the default: `settings.use_signing_order` is `1` unless you turn it off, and recipients sign in ascending `order`.

**1. Create recipients with explicit order**

Give each recipient an `order`. Lower numbers sign first.

**2. Send the request**

Use [`create-and-send`](/api-reference/v01.33.00/signing-requests/create-and-send-signing-request-atomic) for a single call, or [`create`](/api-reference/v01.33.00/signing-requests/create-signing-request) followed by [`/send`](/api-reference/v01.33.00/signing-requests/send-signing-request) if you need a review step first.

**3. Only the first signer is emailed**

Firma emails recipients at `order: 1` immediately. Once they finish, Firma automatically emails the next `order` tier - you don't drive this yourself. Subscribe to [webhooks](/guides/webhooks) instead of polling if you want to track each step.

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Vendor Agreement",
    "template_id": "tmpl_123",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      },
      {
        "first_name": "Bob",
        "last_name": "Smith",
        "email": "bob@example.com",
        "designation": "Signer",
        "order": 2
      }
    ]
  }'
```

Bob does not receive an email until Alice completes her fields. Subscribe to [`signing_request.recipient.signed`](/guides/webhooks) if you want to track each step, and `signing_request.completed` for when the whole chain finishes.

> [!NOTE]
>
> `order` values just need to sort correctly - they don't need to be contiguous. However, tied `order` values (e.g. `1, 2, 2, 5`) do **not** create a parallel signing tier - only one recipient per order value is notified at a time. If you need two signers to sign simultaneously, use the [parallel pattern](#pattern-parallel-signing) with `use_signing_order: false` instead.

## Pattern: Dynamic second signer

This is the case behind most "how do I add a signer mid-flow" tickets: signer 1 fills something in - a referral, a co-signer, a beneficiary - and only then do you know signer 2's email. The instinct is to send the request with just signer 1, then update it to add signer 2 once you know who they are.

> [!WARNING]
>
> **That update is not possible on the same signing request.** Once `sent_on` is set, `PATCH`/`PUT /signing-requests/{id}` and `DELETE /signing-requests/{id}` all return `409 ALREADY_SENT` - a sent signing request is fully immutable, and that includes adding a new recipient. There is no endpoint that adds a recipient to, or changes a recipient's email on, a request that's already been sent. See [Error handling: 409 ALREADY\_SENT](#error-handling-409-already_sent) below for the full list of operations this blocks.

The workaround is to **chain two signing requests** instead of mutating one:

**1. Send request #1 with only signer 1**

Include a field (`type: "text"`, some `variable_name` like `next_signer_email`) for signer 1 to name the next signer. Send it with `create-and-send`, exactly one recipient.

**2. Listen for signer 1's completion**

Since request #1 has a single signer, `signing_request.completed` fires as soon as they finish - you don't need `signing_request.recipient.signed` for this case.

**3. Read the field signer 1 filled in**

The webhook payload doesn't carry field values, so call [`GET /signing-requests/{id}/fields`](/api-reference/v01.33.00/signing-requests/get-signing-request-fields) and read `final_value` off the field with the matching `variable_name`.

**4. Create and send request #2 for signer 2**

Use the email you just extracted. This is a **new** signing request with its own `id`.

> [!WARNING]
>
> Because this is two separate signing requests, it produces two separate completion certificates and two separate audit trails - there is no single certificate covering both signers. If a unified certificate is a hard requirement, the only alternative is to collect signer 2's email *before* sending - e.g., through a form in your own app - rather than mid-flow.

> [!NOTE]
>
> Firma doesn't have a metadata or external-reference field on the signing request itself to link request #1 and request #2 together. Store that mapping (e.g. `original_signing_request_id`) in your own database when you create request #2.

### Approach 1: Webhook-triggered second request

Use this when signers receive email invitations and your backend handles the chain.

```js Node.js (Express) theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()
const API_KEY = process.env.FIRMA_API_KEY
const WEBHOOK_SECRET = process.env.FIRMA_WEBHOOK_SECRET
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

app.post('/webhooks/firma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const payload = req.body.toString('utf8')
    if (!verifySignature(payload, req.headers['x-firma-signature'], WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Invalid signature' })
    }

    const event = JSON.parse(payload)
    res.status(200).json({ received: true }) // ack immediately

    if (event.type !== 'signing_request.completed') return

    const signingRequestId = event.data.signing_request.id

    // Look up whether this request is one of our "signer 1 only" requests
    const original = await db.pendingChains.findOne({ signing_request_id: signingRequestId })
    if (!original) return // not part of a dynamic-signer chain, ignore

    // Signer 1's field values aren't in the webhook payload - fetch them
    const fieldsResp = await fetch(`${API_BASE}/signing-requests/${signingRequestId}/fields`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
    const { results: fields } = await fieldsResp.json()
    const nextSignerField = fields.find(f => f.variable_name === 'next_signer_email')
    const nextSignerEmail = nextSignerField?.final_value

    if (!nextSignerEmail) {
      console.error(`No next_signer_email captured on ${signingRequestId}`)
      return
    }

    // Create and send request #2 for the dynamically-determined signer
    const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${event.data.signing_request.name} - Second Signer`,
        template_id: original.template_id,
        recipients: [
          {
            first_name: 'Next',
            last_name: 'Signer',
            email: nextSignerEmail,
            designation: 'Signer',
            order: 1
          }
        ]
      })
    })
    const created = await createResp.json()

    // Persist the link between the two requests yourself - Firma doesn't track it
    await db.pendingChains.update(
      { signing_request_id: signingRequestId },
      { $set: { chained_signing_request_id: created.id, resolved_at: new Date() } }
    )
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })
  if (!parts.t || !parts.v1) return false
  const signedPayload = `${parts.t}.${payload}`
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
  try {
    return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  } catch {
    return false
  }
}

app.listen(3000)
```

```py Python (Flask) theme={null}
import os
import hmac
import hashlib
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ['FIRMA_API_KEY']
WEBHOOK_SECRET = os.environ['FIRMA_WEBHOOK_SECRET']
API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    payload = request.get_data(as_text=True)
    if not verify_signature(payload, request.headers.get('X-Firma-Signature'), WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    if event['type'] != 'signing_request.completed':
        return jsonify({'received': True}), 200

    signing_request_id = event['data']['signing_request']['id']

    original = db.pending_chains.find_one({'signing_request_id': signing_request_id})
    if not original:
        return jsonify({'received': True}), 200

    fields_resp = requests.get(
        f"{API_BASE}/signing-requests/{signing_request_id}/fields",
        headers={'Authorization': f"Bearer {API_KEY}"}
    )
    fields = fields_resp.json()['results']
    next_signer_field = next((f for f in fields if f.get('variable_name') == 'next_signer_email'), None)
    next_signer_email = next_signer_field.get('final_value') if next_signer_field else None

    if not next_signer_email:
        return jsonify({'received': True}), 200

    create_resp = requests.post(
        f"{API_BASE}/signing-requests/create-and-send",
        headers={'Authorization': f"Bearer {API_KEY}", 'Content-Type': 'application/json'},
        json={
            'name': f"{event['data']['signing_request']['name']} - Second Signer",
            'template_id': original['template_id'],
            'recipients': [{
                'first_name': 'Next',
                'last_name': 'Signer',
                'email': next_signer_email,
                'designation': 'Signer',
                'order': 1
            }]
        }
    )
    created = create_resp.json()

    db.pending_chains.update_one(
        {'signing_request_id': signing_request_id},
        {'$set': {'chained_signing_request_id': created['id']}}
    )

    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
    if not signature_header:
        return False
    parts = dict(p.split('=') for p in signature_header.split(','))
    if 't' not in parts or 'v1' not in parts:
        return False
    signed_payload = f"{parts['t']}.{payload}"
    expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts['v1'], expected)

if __name__ == '__main__':
    app.run(port=3000)
```

> [!TIP]
>
> Respond `200` before doing the field lookup and the follow-up create-and-send call - Firma's webhook delivery times out at 5 seconds, and the pattern above involves two outbound API calls of its own.

### Approach 2: Embedded signing with editable identity fields

Use this when you embed signing directly in your app and want signer 2 to confirm or correct their own identity when they open the signing view - no email-based flow needed.

**1. Create and send request #1 for signer 1**

Include a text field (e.g. `variable_name: "next_signer_email"`) for signer 1 to provide signer 2's email. Set `send_signing_email: false` since you're embedding the signing view yourself.

**2. Embed signer 1's signing view**

Use the [embeddable signing component](/guides/embeddable-signing) to render signer 1's signing view in your app. Listen for the `firma:signing:completed` postMessage event.

**3. On completion, read signer 2's email from the field**

Call `GET /signing-requests/{id}/fields` and read `final_value` from the field with `variable_name: "next_signer_email"`.

**4. Create request #2 with identity\_editable\_fields**

Create a new signing request for signer 2 with `settings.identity_editable_fields` set to `["name", "company"]`. Recognized keys are `name` (covers first and last name together), `phone`, `company`, `title`, and `address`. This lets signer 2 review and correct their own name and company when they open the signing view - useful when signer 1 may have provided approximate details. Note: email is not editable through this mechanism.

**5. Embed signer 2's signing view**

Render signer 2's signing view in your app. Signer 2 sees their pre-filled identity, can correct it if needed, and signs.

```js Frontend (embed + postMessage listener) theme={null}
// Step 1: Your backend creates the signing request and returns the recipient's signing URL
const { signingUrl, signingRequestId } = await fetch('/api/create-dynamic-signer-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId, signer1Email, signer1Name })
}).then(r => r.json())

// Step 2: Embed signer 1's signing view
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-container').appendChild(iframe)

// Step 3: Listen for completion
window.addEventListener('message', async (event) => {
  if (event.data?.type !== 'firma:signing:completed') return

  // Step 4: Your backend reads the field, creates request #2, returns signer 2's signing URL
  const { signingUrl: signer2Url } = await fetch('/api/chain-dynamic-signer', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ originalSigningRequestId: signingRequestId })
  }).then(r => r.json())

  // Step 5: Embed signer 2's signing view
  iframe.src = signer2Url
})
```

```js Backend (Node.js / Express) theme={null}
import express from 'express'

const app = express()
app.use(express.json())

const API_KEY = process.env.FIRMA_API_KEY
const API_BASE = 'https://api.firma.dev/functions/v1/signing-request-api'

// Step 1: Create request #1 for signer 1
app.post('/api/create-dynamic-signer-request', async (req, res) => {
  const { documentId, signer1Email, signer1Name } = req.body

  const resp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Dynamic Signer',
      document_id: documentId,
      settings: { send_signing_email: false },
      recipients: [{
        first_name: signer1Name.split(' ')[0],
        last_name: signer1Name.split(' ').slice(1).join(' ') || signer1Name,
        email: signer1Email,
        designation: 'Signer',
        order: 1
      }],
      fields: [{
        type: 'text',
        variable_name: 'next_signer_email',
        required: true,
        x: 50, y: 700, width: 200, height: 30, page: 0,
        recipient_order: 1
      }]
    })
  })
  const data = await resp.json()
  const recipient = data.recipients[0]
  const signingUrl = `https://app.firma.dev/signing/${recipient.id}`

  res.json({ signingUrl, signingRequestId: data.id })
})

// Steps 3–4: Read signer 2's email, create request #2 with editable identity
app.post('/api/chain-dynamic-signer', async (req, res) => {
  const { originalSigningRequestId } = req.body

  // Read signer 1's field values
  const fieldsResp = await fetch(
    `${API_BASE}/signing-requests/${originalSigningRequestId}/fields`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  )
  const { results: fields } = await fieldsResp.json()
  const nextEmail = fields.find(f => f.variable_name === 'next_signer_email')?.final_value

  if (!nextEmail) return res.status(400).json({ error: 'Signer 1 did not provide next signer email' })

  // Create request #2 with identity_editable_fields
  const createResp = await fetch(`${API_BASE}/signing-requests/create-and-send`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Contract - Second Signer',
      document_id: req.body.documentId || null,
      template_id: req.body.templateId || null,
      settings: {
        send_signing_email: false,
        identity_editable_fields: ['name', 'company'],
        notify_identity_change_email: 1
      },
      recipients: [{
        first_name: 'Signer',
        last_name: '2',
        email: nextEmail,
        designation: 'Signer',
        order: 1
      }]
    })
  })
  const created = await createResp.json()
  const signingUrl = `https://app.firma.dev/signing/${created.recipients[0].id}`

  // Store the link in your own database
  await db.signingChains.insert({
    original_id: originalSigningRequestId,
    chained_id: created.id,
    created_at: new Date()
  })

  res.json({ signingUrl })
})

app.listen(3000)
```

> [!NOTE]
>
> Setting `identity_editable_fields: ["name", "company"]` lets signer 2 update their own name and company in the signing view before signing. Recognized keys: `name` (first + last name together), `phone`, `company`, `title`, `address`. Email is not editable through this mechanism - the email provided when creating the signing request is permanent. Set `notify_identity_change_email: 1` to receive a notification when a signer changes their identity.

## Pattern: Parallel signing

Firma does not have an either-signer slot in which one of two people can choose to sign. Your application must select the recipient before creating the request. For an automatic company countersignature without a human signer, use an [organization seal](/guides/organization-seals).

Use this when signers are independent of each other - nobody needs to wait for anyone else to finish.

Set `settings.use_signing_order: false` on the request. With it off, Firma emails **every** recipient at send time instead of gating later tiers on earlier ones finishing. `order` values are still stored on each recipient, but they aren't enforced - nobody gets an out-of-turn block.

```json theme={null}
{
  "name": "Board Resolution",
  "template_id": "tmpl_123",
  "settings": {
    "use_signing_order": false
  },
  "recipients": [
    { "first_name": "Alice", "last_name": "Johnson", "email": "alice@example.com", "designation": "Signer", "order": 1 },
    { "first_name": "Bob", "last_name": "Smith", "email": "bob@example.com", "designation": "Signer", "order": 2 },
    { "first_name": "Carol", "last_name": "Lee", "email": "carol@example.com", "designation": "Signer", "order": 3 }
  ]
}
```

All three receive their signing email immediately. The request completes (and `signing_request.completed` fires) once all of them have finished, regardless of the order they actually sign in.

## Pattern: Signer and approver

Firma's designation model is deliberately mutually exclusive: a recipient row is a `Signer`, an `Approver`, or `CC` - never more than one. If the same person needs to both sign and then approve, they appear as **two rows** with different `order` values, not one row with two roles.

```json theme={null}
{
  "name": "Expense Report",
  "template_id": "tmpl_123",
  "recipients": [
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Signer",
      "order": 1
    },
    {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "designation": "Approver",
      "order": 2
    }
  ]
}
```

> [!NOTE]
>
> Fields matter here too: `approval_signature`, `approval_checkmark`, and `approval_date` fields can only be assigned to a recipient whose `designation` is `Approver` - assigning one to a `Signer` row returns a `400`. Their value is authored server-side when the approver completes their review; you don't submit one yourself.

This also composes with sequential signing: give the `Signer` row a lower `order` than the `Approver` row, and Alice's own approval step won't unlock until she's finished signing.

## Error handling: 409 `ALREADY_SENT`

`ALREADY_SENT` means the signing request has a `sent_on` timestamp and the operation you tried only works on a draft. It's returned, at `409`, from:

| Endpoint | Trigger |
| :- | :- |
| `PATCH /signing-requests/{id}` | Request has been sent - no property, recipient, or field update is allowed |
| `PUT /signing-requests/{id}` | Same - comprehensive update also requires `not_sent` |
| `DELETE /signing-requests/{id}` | Sent requests can't be deleted; the error message points you to [`/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) instead |

What you *can* still do to a sent-but-not-finished request:

* [`POST /signing-requests/{id}/resend`](/api-reference/v01.33.00/signing-requests/resend-signing-request-to-specific-recipients) - re-sends the notification email to recipients who are currently at the active signing tier and haven't finished yet. It does not let you change their email or any other recipient data.
* [`POST /signing-requests/{id}/cancel`](/api-reference/v01.33.00/signing-requests/cancel-a-signing-request) - stops the whole request for everyone.

If you hit `ALREADY_SENT` while trying to fix a typo'd recipient email or add a recipient you forgot, there's no in-place fix - cancel and recreate, or (for the "didn't know the second recipient yet" case) use the [dynamic second signer](#pattern-dynamic-second-signer) pattern above.

## Next steps

* [Sending a signing request](/guides/sending-signing-request) - the base create/send flow these patterns build on
* [Webhooks](/guides/webhooks) - event types, signature verification, and retry behavior
* [Field prefilling](/guides/field-prefilling) - populate fields with known data instead of asking a signer to fill them in


# Supabase
Source: https://docs.firma.dev/guides/supabase-integration

Add legally binding e-signatures to any Supabase application using Edge Functions, Postgres, and webhooks.

Add legally binding e-signatures to any Supabase application. Use Supabase Edge Functions to call the Firma API, store signing status in your Postgres database, and receive real-time updates via webhooks.

## What you can build

* **Contract signing flows** — trigger signing requests when users complete a form or checkout
* **Document status dashboards** — track which documents are pending, signed, or declined
* **Embedded signing** — let users sign documents without leaving your app
* **Automated workflows** — use Firma webhooks + Supabase database triggers to kick off downstream actions when documents are signed

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A Supabase project with Edge Functions enabled
* The [Supabase CLI](https://supabase.com/docs/guides/cli) installed locally

## Architecture overview

```text theme={null}
Your Frontend (React, Next.js, Flutter, etc.)
        │
        ▼
Supabase Edge Function ──► Firma API
        │                      │
        ▼                      │ (webhook)
Supabase Postgres  ◄──────────┘
  (signing_requests table)
```

Your frontend calls a Supabase Edge Function, which securely calls the Firma API to create signing requests. When recipients sign (or decline), Firma sends a webhook to another Edge Function that updates your database.

## Step 1: Store your Firma API key

Add your Firma API key as a Supabase secret so Edge Functions can access it securely:

```bash theme={null}
supabase secrets set FIRMA_API_KEY=your_api_key_here
```

## Step 2: Create a table to track signing requests

Run this SQL in the Supabase SQL Editor to create a table for tracking document status:

```sql theme={null}
create table signing_requests (
  id uuid primary key default gen_random_uuid(),
  firma_request_id text unique,
  user_id uuid references auth.users(id),
  template_id text,
  status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Enable Row Level Security
alter table signing_requests enable row level security;

-- Users can only see their own signing requests
create policy "Users can view own requests"
  on signing_requests for select
  using (auth.uid() = user_id);
```

## Step 3: Create an Edge Function to send signing requests

Generate a new Edge Function:

```bash theme={null}
supabase functions new send-signing-request
```

Then replace the contents of `supabase/functions/send-signing-request/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers": "authorization, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const { template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  // Get the authenticated user
  const authHeader = req.headers.get("Authorization")!;
  const {
    data: { user },
  } = await supabase.auth.getUser(authHeader.replace("Bearer ", ""));

  if (!user) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Create a signing request via Firma API
  const firmaResponse = await fetch(
    "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send",
    {
      method: "POST",
      headers: {
        Authorization: Deno.env.get("FIRMA_API_KEY"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const firmaData = await firmaResponse.json();

  if (!firmaResponse.ok) {
    return new Response(JSON.stringify({ error: firmaData }), {
      status: firmaResponse.status,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  // Store the signing request in your database
  const { error } = await supabase.from("signing_requests").insert({
    firma_request_id: firmaData.id,
    user_id: user.id,
    template_id,
    status: "pending",
  });

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  }

  return new Response(JSON.stringify(firmaData), {
    status: 201,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
});
```

Deploy it:

```bash theme={null}
supabase functions deploy send-signing-request
```

## Step 4: Handle Firma webhooks

Create another Edge Function to receive webhook events from Firma when documents are signed, declined, or updated:

```bash theme={null}
supabase functions new firma-webhook
```

Replace the contents of `supabase/functions/firma-webhook/index.ts`:

```typescript theme={null}
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!
  );

  const payload = await req.json();
  const { type, data } = payload;

  // Map Firma event types to a simple status
  const statusMap: Record<string, string> = {
    "signing_request.completed": "completed",
    "signing_request.cancelled": "cancelled",
    "signing_request.expired": "expired",
    "signing_request.sent": "sent",
    "signing_request.recipient.signed": "recipient_signed",
    "signing_request.recipient.declined": "declined",
  };

  const status = statusMap[type];
  if (!status) {
    // Event type we don't need to track
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // The signing request ID is nested inside data.signing_request
  const signingRequestId = data.signing_request?.id;
  if (!signingRequestId) {
    return new Response(JSON.stringify({ error: "Missing signing request ID" }), {
      status: 400,
    });
  }

  const { error } = await supabase
    .from("signing_requests")
    .update({
      status,
      updated_at: new Date().toISOString(),
    })
    .eq("firma_request_id", signingRequestId);

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
});
```

Deploy it and make it publicly accessible (webhooks don't send auth headers):

```bash theme={null}
supabase functions deploy firma-webhook --no-verify-jwt
```

Then register the webhook URL in your Firma dashboard under **Settings → Webhooks**. Your endpoint URL will be:

```text theme={null}
https://<your-project-ref>.supabase.co/functions/v1/firma-webhook
```

> [!WARNING]
>
> For production use, verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for details on signature verification.

## Step 5: Embed the signing experience (optional)

For an in-app signing experience, use Firma's [embeddable signing](/guides/embeddable-signing) component. Once you have the `signing_request_user_id` from the API response, load it in an iframe:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Step 6: Query signing status from your frontend

With Row Level Security in place, your frontend can query the signing status directly:

```typescript theme={null}
const { data: requests } = await supabase
  .from("signing_requests")
  .select("*")
  .order("created_at", { ascending: false });
```

## Next steps

* [Firma API reference](/api-reference) — full endpoint documentation
* [Webhooks guide](/guides/webhooks) — event types and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [White-labeling](/guides/white-labeling) — customize emails and branding
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps


# Trae
Source: https://docs.firma.dev/guides/trae-integration

Add legally binding e-signatures to apps you build in Trae using Firma's MCP servers and a backend function.

Firma lets you add legally binding e-signatures to any app you build in Trae, ByteDance's AI-native IDE. Because Trae has a native MCP marketplace and multi-agent collaboration, the cleanest integration is to connect Firma's MCP servers so Trae's agents can generate accurate Firma code on demand.

This guide covers two integration paths:

1. **MCP-assisted generation (recommended)** - Connect the Firma Docs and Data MCP servers so Trae's agents can read documentation and Firma account state while writing code.
2. **Direct REST integration** - Skip MCP and call the Firma REST API directly from a backend function in the app Trae generates.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* Trae installed (free)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Getting started

**MCP-assisted generation**

This is the recommended path. You connect Firma's MCP servers once, and from then on Trae's agents can generate Firma integration code for any app you build.

### Step 1: Add the Firma MCP servers to Trae

Open Trae and go to the MCP settings panel. Add two servers:

* **Firma Docs** - URL: `https://docs.firma.dev/mcp`. Lets the agent search Firma documentation and API reference.
* **Firma Data** - URL: `https://mcp.firma.dev/mcp`. Lets the agent read your Firma account state (templates, signing requests, recipients). Requires authentication on first connection.

The Data MCP server is optional. Use it when you want the agent to pick the right template ID for you instead of asking.

### Step 2: Store your API key

In your Trae project, create a `.env` file and add your Firma API key:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`. Never expose your API key in frontend code. Always call the Firma API from a backend function where secrets are kept secure.

### Step 3: Ask Trae's agent to generate the integration

With the MCP servers connected and the API key set, ask the Trae agent directly. A typical prompt:

```text theme={null}
Add an endpoint at /api/signing-requests that uses the Firma create-and-send
endpoint to send a signing request. Read the request body for name, template_id,
signer_email, signer_first_name, and signer_last_name. Use the FIRMA_API_KEY
from environment variables. Reference the Firma docs MCP for the exact request shape.
```

Because the agent reads the Firma Docs MCP server, the generated code will use the correct endpoint URL, headers, and request body without hallucinations. The output should look close to this for a Node.js backend:

```typescript theme={null}
import express from "express";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";
const app = express();
app.use(express.json());

app.post("/api/signing-requests", async (req, res) => {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    req.body;

  const apiKey = process.env.FIRMA_API_KEY;

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) return res.status(response.status).json({ error: data });
  res.json({
    signing_request_id: data.id,
    signing_request_user_id: data.first_signer.id,
    signing_link: data.first_signer.signing_link,
  });
});

app.listen(3000);
```

The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, ask the agent to use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

### Step 4: Wire the endpoint to your app UI

Ask the agent again:

```text theme={null}
On the contract page, when the user clicks Send, POST to /api/signing-requests
with the form fields and then open the returned signing_request_user_id in a
signing iframe.
```

Trae's multi-agent setup will edit both the frontend component and the backend route in one pass.

**Direct REST integration**

If you prefer not to use MCP, copy the backend code from the MCP-assisted tab above into any project Trae generates. The Firma REST API works the same way regardless of how you author the integration.

### Step 1: Store your API key

Create a `.env` file in your project root:

```text theme={null}
FIRMA_API_KEY=your-firma-api-key
```

Make sure `.env` is in `.gitignore`.

### Step 2: Create the backend endpoint

Ask Trae's agent to create the endpoint, or paste the Express example from the MCP-assisted tab directly into your project. The key details:

* **Endpoint:** `POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send`
* **Authorization:** Raw API key in the `Authorization` header (no `Bearer` prefix)
* **Required fields:** `name`, `template_id`, and a `recipients` array
* **Response:** `first_signer.id` (the signing request user ID) and `first_signer.signing_link`

## Webhook integration

To track when documents are signed, ask the Trae agent to add a webhook receiver:

```text theme={null}
Add an endpoint at /api/firma-webhook that handles incoming Firma webhook events.
When the type is signing_request.completed, mark the related contract as signed
in the database.
```

The agent will generate something like this:

```typescript theme={null}
app.post("/api/firma-webhook", async (req, res) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;
    // Update your database or trigger the next workflow step.
  }

  res.json({ received: true });
});
```

In the Firma dashboard under **Settings > Webhooks**, register a webhook pointing to your endpoint URL. Firma sends events for key state changes. See the [webhooks guide](/guides/webhooks) for all event types.

> [!WARNING]
>
> Always verify the webhook signature using your Firma webhook signing secret in production. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents directly in your UI, Firma provides an embeddable signing experience. Once you have the recipient's `signing_request_user_id` from the API (returned as `first_signer.id` in the `create-and-send` response), load it in an iframe inside your Trae-built app:

```html theme={null}
<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup instructions including security best practices.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - Event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - In-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - Multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - End-to-end Firma integration walkthrough
* [API reference](/api-reference) - Full endpoint documentation


# TypeScript SDK for the Firma.dev API
Source: https://docs.firma.dev/guides/typescript-sdk

Install @firma-dev/sdk, authenticate, and call every Firma.dev endpoint from TypeScript with typed requests, responses, pagination, and error handling.

The `@firma-dev/sdk` package is the official TypeScript client for the Firma.dev API. It ships fully typed request and response models, resolves the correct base URL for you, and exposes every endpoint as a typed method, so you get editor autocompletion and compile-time safety instead of hand-rolled `fetch` calls.

> [!NOTE]
>
> The SDK is generated directly from the same OpenAPI specification that powers this API reference, so its methods and types always match the endpoints documented here.

## Prerequisites

* Node.js 18 or later (the SDK uses the built-in `fetch`).
* A Firma.dev API key. See [Authentication](/guides/authentication) for how to create one and which key (live vs. test) to use.

## Installation

```bash npm theme={null}
npm install @firma-dev/sdk
```

```bash pnpm theme={null}
pnpm add @firma-dev/sdk
```

```bash yarn theme={null}
yarn add @firma-dev/sdk
```

## Authentication

Create a client with your API key. The key is sent on every request as the `Authorization` header; the SDK handles that for you, so you never build the header yourself.

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });
```

> [!WARNING]
>
> Never hard-code an API key in client-side code or commit it to source control. Load it from an environment variable or a secrets manager. The SDK is intended for server-side use.

## Quickstart

List the templates in your workspace:

```typescript theme={null}
import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

const templates = await firma.templates.listTemplates();
console.log(templates);
```

Awaiting a method returns the parsed response body directly. If you also need the HTTP status or headers, call `.withRawResponse()` (see [Responses and raw access](#responses-and-raw-access)).

## Common operations

Every endpoint in this API reference is available as a typed method, grouped by resource (`firma.templates`, `firma.signingRequests`, `firma.webhooks`, and so on). The examples below cover the most common flows.

### Templates

```typescript theme={null}
// List with filters and pagination
const page = await firma.templates.listTemplates({ page_size: 20, name: "contract" });

// Fetch one
const template = await firma.templates.getTemplate({ id: templateId });

// Create from a base64-encoded PDF or DOCX
const created = await firma.templates.createTemplate({
  name: "Employment Contract Template",
  document: base64Document,
});

// Partially update
await firma.templates.patchTemplate({
  id: created.id,
  body: { name: "Updated name", expiration_hours: 72 },
});
```

### Signing requests

```typescript theme={null}
// List
const requests = await firma.signingRequests.listSigningRequests({ page_size: 10 });

// Fetch one
const request = await firma.signingRequests.getSigningRequest({ id: signingRequestId });

// Cancel
await firma.signingRequests.cancelSigningRequest({
  id: signingRequestId,
  reason: "No longer needed",
  notify_signers: true,
});
```

> [!NOTE]
>
> Creating and sending a signing request takes a larger structured payload (recipients, fields, settings). Open the **Create and send signing request** page in the API reference and select the `@firma-dev/sdk` tab to copy the exact typed call for your parameters.

### Webhooks

```typescript theme={null}
// Subscribe to events
const webhook = await firma.webhooks.createWebhook({
  url: "https://example.com/firma-webhook",
  events: ["signing_request.completed"],
});

// List existing subscriptions
const webhooks = await firma.webhooks.listWebhooks();
```

See [Webhooks](/guides/webhooks) for the full list of event types and payload shapes.

## Responses and raw access

By default, awaiting a call resolves to the response body. To inspect the underlying HTTP response, use `.withRawResponse()`:

```typescript theme={null}
const { data, rawResponse } = await firma.templates
  .listTemplates()
  .withRawResponse();

console.log(rawResponse.status);
console.log(rawResponse.headers.get("x-request-id"));
console.log(data);
```

## Error handling

Failed requests throw a typed error you can catch. Errors carry the HTTP status code and the parsed error body returned by the API.

```typescript theme={null}
import { FirmaClient, FirmaError } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: process.env.FIRMA_API_KEY });

try {
  await firma.templates.getTemplate({ id: "does-not-exist" });
} catch (err) {
  if (err instanceof FirmaError) {
    console.error(err.statusCode); // e.g. 404
    console.error(err.body); // parsed error payload
  } else {
    throw err;
  }
}
```

## Pagination

List endpoints accept `page` and `page_size` and return a `pagination` object alongside the results. Iterate by incrementing `page` until you have collected every item:

```typescript theme={null}
async function getAllTemplates() {
  const all = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await firma.templates.listTemplates({ page, page_size: 100 });
    all.push(...res.results);
    totalPages = res.pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return all;
}
```

> [!NOTE]
>
> Field names on the pagination object follow the response schema shown on each list endpoint in the API reference. Check the endpoint page if you are unsure of the exact shape.

## Next steps

> **[Authentication](/guides/authentication)**
>
> Create and manage the API keys the SDK authenticates with.

> **[Webhooks](/guides/webhooks)**
>
> Receive real-time events for signing request lifecycle changes.

> **[Sending a signing request](/guides/sending-signing-request)**
>
> Walk through the full send flow the SDK methods map to.

> **[API reference](/api-reference/v01.28.00/templates/list-templates)**
>
> Every endpoint, each with a copy-paste `@firma-dev/sdk` example.


# v0
Source: https://docs.firma.dev/guides/v0-integration

Add legally binding e-signatures to any v0 app using Next.js route handlers and environment variables.

Firma lets you add legally binding e-signatures to any v0 application. Use Next.js route handlers to call the Firma REST API, send signing requests, and receive webhook events when documents are signed. This guide walks through the full flow: storing your API key, sending a signing request, wiring it to your UI, and handling completion events.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [v0](https://v0.dev) account with an active project (free tier works)
* At least one Firma template with signing fields configured

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value — do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

v0 manages environment variables through the Vars panel in the chat sidebar. Values are synced with the connected Vercel project, so the same secret works in previews and in production.

1. Open your v0 project and click the **Vars** tab in the sidebar
2. Click **Add Variable**
3. Set the key to `FIRMA_API_KEY` and paste your Firma API key as the value
4. Save

The variable is now available as `process.env.FIRMA_API_KEY` in any server-side code v0 generates.

> [!WARNING]
>
> Never expose your API key in client components. Always call the Firma API from route handlers or server actions, not from `"use client"` files.

## Step 2: Create a route handler to send signing requests

Ask v0 to create a route handler, or add the file directly. v0 generates Next.js App Router code by default, so route handlers live in `app/api/<route-name>/route.ts`.

This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// app/api/send-signing-request/route.ts
import { NextRequest, NextResponse } from "next/server";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

export async function POST(req: NextRequest) {
  const { name, template_id, signer_email, signer_first_name, signer_last_name } =
    await req.json();

  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    return NextResponse.json(
      { error: "FIRMA_API_KEY not configured" },
      { status: 500 }
    );
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name,
        template_id,
        recipients: [
          {
            first_name: signer_first_name,
            last_name: signer_last_name,
            email: signer_email,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    return NextResponse.json({ error: data }, { status: response.status });
  }

  return NextResponse.json({
    signing_request_id: data.id,
    status: "sent",
  });
}
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 3: Call the route handler from your UI

From a client component, POST to your new route when the user completes the form:

```typescript theme={null}
// components/send-contract-button.tsx
"use client";

import { useState } from "react";

export function SendContractButton({ templateId }: { templateId: string }) {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    const res = await fetch("/api/send-signing-request", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: "NDA for Alice Johnson",
        template_id: templateId,
        signer_email: "alice@example.com",
        signer_first_name: "Alice",
        signer_last_name: "Johnson",
      }),
    });
    const data = await res.json();
    setLoading(false);
    console.log(data);
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

You can also ask v0's chat to wire this up: *"When the user submits the contract form, call `/api/send-signing-request` with the template ID, signer email, first name, and last name from the form."* v0 will generate the form, the button, and the fetch call together.

## Webhook integration

To track when documents are signed, add a webhook route handler and register it in the Firma dashboard.

```typescript theme={null}
// app/api/webhooks/firma/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { type, data } = payload;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update your database, send a notification, or trigger
    // the next step in your workflow
    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  return NextResponse.json({ received: true });
}
```

Then register the webhook:

1. Publish your app (see below) so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Publishing to Vercel

v0 projects connect to a Vercel project automatically. To push your app to production:

1. Click **Publish** in the top right of the v0 interface, or connect an existing Vercel project from **Project settings**
2. Environment variables set in the Vars panel sync to Vercel automatically. To scope values per environment (Production, Preview, Development), edit them under **Project → Settings → Environment Variables** in the Vercel dashboard
3. Once published, your webhook URL will be `https://<project-name>.vercel.app/api/webhooks/firma`. Use that when registering the webhook in Firma

> [!NOTE]
>
> If you need a different Firma API key for preview vs. production, set `FIRMA_API_KEY` per environment in the Vercel dashboard. v0's Vars panel writes to all environments by default.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// components/embedded-signing.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that v0's chat can connect to directly. When connected, v0 searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns.

To set it up:

1. In v0, click **Add MCP** on the prompt form or go to **Settings → MCP Connections**
2. Add a custom MCP server with the URL: `https://docs.firma.dev/mcp`
3. Save

From that point, prompts like *"Add a Firma route handler that sends a signing request from template `abc123` using the email in the form"* will generate code that matches the current Firma API. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) — API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) — event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) — in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) — multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) — end-to-end Firma integration walkthrough
* [API reference](/api-reference) — full endpoint documentation


# Wasp (Open SaaS)
Source: https://docs.firma.dev/guides/wasp-integration

Add legally binding e-signatures to any Wasp application using server-side actions and the Firma REST API.

Firma lets you add legally binding e-signatures to any application built with [Wasp](https://wasp-lang.dev). Since Wasp generates a full-stack React + Node.js app with built-in auth, database (Prisma), and server actions, the integration is straightforward: create a Wasp action that calls the Firma API, and invoke it from your React frontend.

This guide is especially useful if you are building on the [Open SaaS](https://opensaas.sh) template, which already includes auth, payments, and a database. Adding e-signatures is a natural extension for SaaS apps in legal, HR, consulting, and real estate verticals.

## Prerequisites

* A [Firma account](https://app.firma.dev) with an API key
* A [Wasp](https://wasp-lang.dev) project (v0.15+ recommended) or an Open SaaS project
* At least one Firma template with signing fields configured
* Node.js 18+ installed locally

> [!NOTE]
>
> Firma uses the raw API key as the `Authorization` header value - do not prefix it with `Bearer`. This differs from many other APIs.

## Step 1: Store your API key as an environment variable

Add your Firma API key to the `.env.server` file in your project root:

```text theme={null}
FIRMA_API_KEY=your_api_key_here
```

Wasp separates client and server environment variables. Using `.env.server` ensures the key is only available in server-side code and never reaches the browser.

> [!WARNING]
>
> Never expose your API key in client-side code. Wasp actions run on the server by default, so your key stays safe as long as you only use it inside actions.

## Step 2: Define the action in your Wasp file

Add a server action declaration to your `main.wasp` file:

```wasp theme={null}
action sendSigningRequest {
  fn: import { sendSigningRequest } from "@src/signing/actions",
  entities: [SigningRequest]
}
```

If you want to track signing requests in your database, add a Prisma model to your `schema.prisma` file:

```prisma theme={null}
model SigningRequest {
  id              String   @id @default(uuid())
  firmaRequestId  String   @unique
  templateId      String
  signerEmail     String
  status          String   @default("sent")
  userId          String
  user            User     @relation(fields: [userId], references: [id])
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}
```

Then run the migration:

```bash theme={null}
wasp db migrate-dev
```

## Step 3: Implement the server action

Create `src/signing/actions.ts`. This example creates and sends a signing request from a template in a single call using the `create-and-send` endpoint:

```typescript theme={null}
// src/signing/actions.ts
import { type SendSigningRequest } from "wasp/server/operations";

const FIRMA_API = "https://api.firma.dev/functions/v1/signing-request-api";

type SendSigningRequestInput = {
  templateId: string;
  signerEmail: string;
  signerFirstName: string;
  signerLastName: string;
};

export const sendSigningRequest: SendSigningRequest<
  SendSigningRequestInput,
  { signingRequestId: string; status: string }
> = async (args, context) => {
  const apiKey = process.env.FIRMA_API_KEY;
  if (!apiKey) {
    throw new Error("FIRMA_API_KEY not configured");
  }

  const response = await fetch(
    `${FIRMA_API}/signing-requests/create-and-send`,
    {
      method: "POST",
      headers: {
        Authorization: apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Contract for " + args.signerFirstName + " " + args.signerLastName,
        template_id: args.templateId,
        recipients: [
          {
            first_name: args.signerFirstName,
            last_name: args.signerLastName,
            email: args.signerEmail,
            designation: "Signer",
            order: 1,
          },
        ],
      }),
    }
  );

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message || "Failed to send signing request");
  }

  // Store the signing request in your database
  await context.entities.SigningRequest.create({
    data: {
      firmaRequestId: data.id,
      templateId: args.templateId,
      signerEmail: args.signerEmail,
      userId: context.user.id,
    },
  });

  return { signingRequestId: data.id, status: "sent" };
};
```

> [!NOTE]
>
> The `create-and-send` endpoint creates the signing request and sends it to recipients atomically. If you need to review or modify the request before sending, use `POST /signing-requests` to create a draft, then `POST /signing-requests/{id}/send` separately.

## Step 4: Call the action from your React frontend

Import the action from `wasp/client/operations` and call it when the user submits a form:

```typescript theme={null}
// src/signing/SendContractPage.tsx
import { sendSigningRequest } from "wasp/client/operations";
import { useState } from "react";

export function SendContractPage() {
  const [loading, setLoading] = useState(false);

  async function handleSend() {
    setLoading(true);
    try {
      const result = await sendSigningRequest({
        templateId: "your-template-id",
        signerEmail: "alice@example.com",
        signerFirstName: "Alice",
        signerLastName: "Johnson",
      });
      console.log("Signing request sent:", result.signingRequestId);
    } catch (error) {
      console.error("Failed to send:", error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <button onClick={handleSend} disabled={loading}>
      {loading ? "Sending..." : "Send contract"}
    </button>
  );
}
```

Wasp handles the client-server communication automatically. The `sendSigningRequest` import is a type-safe RPC call to your server action - no manual `fetch` needed.

## Webhook integration

To track when documents are signed, declare an API route in your `main.wasp` file and implement a handler that processes Firma webhook events.

Add the API route to `main.wasp`:

```wasp theme={null}
api firmaWebhook {
  fn: import { firmaWebhook } from "@src/signing/webhooks",
  httpRoute: (POST, "/api/webhooks/firma"),
  auth: false
}
```

Then create the handler:

```typescript theme={null}
// src/signing/webhooks.ts
import { type FirmaWebhook } from "wasp/server/api";
import { prisma } from "wasp/server";

export const firmaWebhook: FirmaWebhook = async (req, res, _context) => {
  const { type, data } = req.body;

  if (type === "signing_request.completed") {
    const signingRequestId = data.signing_request.id;

    // Update the signing request status in your database
    await prisma.signingRequest.updateMany({
      where: { firmaRequestId: signingRequestId },
      data: { status: "completed" },
    });

    console.log(`Signing request ${signingRequestId} completed`);
  }

  if (type === "signing_request.recipient.signed") {
    const recipientEmail = data.recipient?.email;
    console.log(`${recipientEmail} signed the document`);
  }

  res.json({ received: true });
};
```

Then register the webhook:

1. Deploy your app so the route is publicly reachable
2. In the Firma dashboard under **Settings → Webhooks**, add a webhook pointing to `https://<your-app-domain>/api/webhooks/firma`
3. Select the events you want to receive. See the [webhooks guide](/guides/webhooks) for all event types and signature verification

> [!WARNING]
>
> For production use, always verify the webhook signature using your Firma webhook signing secret. See the [webhooks guide](/guides/webhooks) for implementation details.

## Embedded signing

For apps where signers complete documents inside your UI instead of jumping to email, Firma provides an embeddable signing experience. The `create-and-send` response includes a `first_signer.id` (the `signing_request_user_id`) and a ready-made `first_signer.signing_link`. Render it in an iframe:

```typescript theme={null}
// src/signing/EmbeddedSigning.tsx
export function EmbeddedSigning({
  signingRequestUserId,
}: {
  signingRequestUserId: string;
}) {
  return (
    <iframe
      src={`https://app.firma.dev/signing/${signingRequestUserId}`}
      style={{ width: "100%", height: "900px", border: 0 }}
      allow="camera; microphone; clipboard-write"
      title="Document Signing"
    />
  );
}
```

See the [embedded signing guide](/guides/embeddable-signing) for full setup including security best practices.

## Bonus: MCP connection for AI-assisted building

Firma offers a [Docs MCP server](/guides/mcp) that AI coding tools can connect to directly. When connected, your AI assistant searches Firma documentation while generating code so it uses accurate endpoints, field names, and patterns. This is a build-time aid and does not affect your deployed app.

## Next steps

* [API authentication](/guides/authentication) - API keys and workspace scoping
* [Webhooks guide](/guides/webhooks) - event types, payloads, and signature verification
* [Embedded signing](/guides/embeddable-signing) - in-app signing experience
* [Creating workspaces](/guides/creating-workspaces) - multi-tenant setups for SaaS apps
* [Complete setup guide](/guides/complete-setup-guide) - end-to-end Firma integration walkthrough
* [API reference](/api-reference) - full endpoint documentation


# Webhooks
Source: https://docs.firma.dev/guides/webhooks

Implement secure webhook integrations to receive real-time event notifications from Firma.

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

## Common use cases

* Send internal notifications when documents are signed
* Update your database when signing requests are completed
* Trigger downstream workflows (invoicing, provisioning, etc.)
* Track signing request status changes in real-time

## Event types

Firma sends the following event types:

### Signing Request Events

* `signing_request.created` - New signing request created
* `signing_request.sent` - Signing request sent to recipients
* `signing_request.viewed` - Recipient viewed the document
* `signing_request.completed` - All recipients finished signing
* `signing_request.expired` - Signing request expired
* `signing_request.cancelled` - Signing request was cancelled
* `signing_request.updated` - Signing request metadata updated
* `signing_request.deleted` - Signing request deleted (before sending)
* `signing_request.certificate.generated` - Signing certificate generated
* `signing_request.reminder.sent` - Reminder sent to recipients

### Recipient Events

* `signing_request.recipient.signed` - Recipient completed signing
* `signing_request.recipient.declined` - Recipient declined to sign
* `signing_request.recipient.identity_changed` - Recipient changed their identity (name, company, etc.) during signing

### Template Events

* `template.updated` - Template modified
* `template.used` - Template used to create a signing request

### Organization Seal Events

* `organization_seal.created` - New seal created
* `organization_seal.updated` - Seal image replaced (new version), renamed, or default flag changed
* `organization_seal.deleted` - Seal revoked
* `organization_seal.erased` - Revoked seal lineage permanently erased

### Signing Request Seal Events

* `signing_request.seal.applied` - Seal applied to a document
* `signing_request.seal.paused` - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
* `signing_request.seal.swapped` - Paused seal participant swapped to a different seal

### Workspace Events

* `workspace.created` - New workspace created
* `workspace.updated` - Workspace modified

### Domain Events

* `domain.verified` - Domain verified successfully
* `domain.verification.failed` - Domain verification failed

## Two levels of enablement

Webhook delivery requires the webhook's own switch and the master switch for its scope. Company webhooks use the company master switch. Workspace webhooks use that workspace's master switch and do not require the company switch.

| Switch | Scope | Where it's set |
| - | - | - |
| Per-webhook `enabled` | An individual webhook subscription | Set on the webhook itself (`PUT /webhooks/{id}`) |
| Master switch | Company or workspace | Company: dashboard **Settings > Webhooks > Enable Webhooks** toggle only. Workspace: dashboard, or `PATCH /workspaces/{id}` with `{"webhook_enabled": true}` |

At least one scope (company or workspace) must have its master switch on for any webhook under that scope to deliver. Turning on the workspace master switch also generates a signing secret for that workspace if one doesn't already exist.

> [!WARNING]
>
> `POST /webhooks/{id}/test` bypasses the master switch. A test delivery can succeed even while the master switch is off and live events are not being delivered - a passing test is not confirmation that real events will fire.

When the master switch is off, Firma skips the event before logging a delivery attempt. `consecutive_failures` stays at `0` and the webhook shows no failure history, even though nothing is being delivered - there's no error to alert you.

### Permissions

Toggling the company-level master switch requires **owner or admin** access to the company; view-only members cannot enable or disable it. Attempting to toggle it without sufficient permissions returns a permission error.

## Creating a webhook

Create webhooks via the API or dashboard:

```bash theme={null}
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'
```

> [!NOTE]
>
> Your webhook URL must use HTTPS and respond within 5 seconds. Use `POST /webhooks/{id}/test` after creation to verify your endpoint is receiving events correctly.

## Webhook payload structure

All webhook events follow this standard structure:

```json theme={null}
{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}
```

> [!NOTE]
>
> Test deliveries from `POST /webhooks/{id}/test` use a different shape: `type` (`webhook.test`), `webhook_id`, `timestamp` and `data`. They have no `id`, so skip your idempotency check for them.

## Security: Signature verification (Required)

> [!WARNING]
>
> **Always verify webhook signatures** to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

* `X-Firma-Signature` - HMAC signature using current signing secret
* `X-Firma-Signature-Old` - HMAC signature using previous secret (during 7-day rotation grace period)
* `X-Firma-Event` - Event type (e.g., `signing_request.completed`)
* `X-Firma-Delivery` - ID of this event's delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload `id` to identify the event.

### Signature format

Firma uses a timestamped signature header:

* Header: `X-Firma-Signature: t=1707500000,v1=abc123def456...`
* `t` = Unix timestamp (seconds) when the signature was generated
* `v1` = HMAC-SHA256 hex digest
* Signed payload format: `{timestamp}.{json_body}`
* The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don't hex-decode it.
* `X-Firma-Signature` and `X-Firma-Signature-Old` each carry their own `t`, so read the timestamp from the header you are verifying.

Example:

```
1707500000.{"id":"evt_123","type":"signing_request.completed",...}
```

### Get your signing secret

1. Navigate to your [Firma dashboard](https://app.firma.dev/settings)
2. View webhook details to retrieve the signing secret
3. Store the secret securely (environment variable or secrets manager)

### Verification example - Node.js (Express)

```js theme={null}
import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)
```

### Verification example - Python (Flask)

```py theme={null}
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, signing_secret)):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)
```

## Handling secret rotation

Rotate your webhook signing secret from the dashboard, or with `POST /webhooks/rotate-secret` for company webhooks or `POST /workspaces/{id}/webhooks/rotate-secret` for workspace webhooks. Through the API, you can rotate a secret once per hour. Workspace webhooks are signed with that workspace's own secret, not the company secret.

1. Firma generates a new secret
2. For 7 days, Firma sends **both** signatures:

* `X-Firma-Signature` (new secret)
* `X-Firma-Signature-Old` (previous secret)

3. After 7 days, only `X-Firma-Signature` is sent. `GET /webhooks/secret-status` or `GET /workspaces/{id}/webhooks/secret-status` returns `grace_period_ends_at`.

> [!WARNING]
>
> Firma keeps only one previous secret. If you rotate again within the 7 days, the previous secret is replaced, and an endpoint that still holds the secret from before the first rotation stops verifying deliveries at once. Deploy each new secret before you rotate again.

**Implementation**: Verify `X-Firma-Signature` with the secret your endpoint is configured with. If that fails, verify `X-Firma-Signature-Old` with the same secret. Until you deploy the new secret, your configured secret is the previous one, which is the one `X-Firma-Signature-Old` is signed with. After you deploy it, `X-Firma-Signature` matches. Deploy the new secret within the 7 days, and configure one secret at a time: an endpoint that accepts both secrets keeps trusting the old one.

### If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

From then on, a request signed with the old secret fails both checks at your endpoint, even while Firma still sends `X-Firma-Signature-Old`, so the 7-day overlap does not extend trust in the old secret.

## Retry behavior

Firma does not follow HTTP redirects when delivering webhooks. Register the exact URL your server serves, including its scheme, hostname, path, and trailing-slash form.

Firma automatically retries failed webhook deliveries:

* **Attempts**: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
* **Timeout**: Your endpoint must respond within 5 seconds
* **Success**: Any 2xx status code indicates success. Redirects count as failures.
* **Same event, new signature**: Every attempt carries the same `X-Firma-Delivery` and, for real events, the same payload `id`, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
* **Auto-disable**: When `consecutive_failures` reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with `PUT /webhooks/{id}` (`"enabled": true`) or in the dashboard.
* **After the last attempt**: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
* **Not retried**: Test deliveries from `POST /webhooks/{id}/test` are sent once. A delivery to a URL that fails Firma's delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

> [!TIP]
>
> **Best practice**: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

### Delivery limits

Webhooks are notifications, not a complete event log:

* Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload `created_at` as a hint and fetch the current state from the API.
* Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
* When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
* There is no API to list or replay events. To reconcile after an outage, list signing requests with `GET /signing-requests` (for example `status=finished&sort_by=finished_on&sort_order=desc`) and fetch each one with `GET /signing-requests/{id}`.

## Idempotency

Always handle duplicate events using the event `id`:

```js theme={null}
async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}
```

## Monitoring webhook health

Monitor your webhook's health by checking the webhook details:

```bash theme={null}
## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes:

* `consecutive_failures` - Failure counter used for automatic disabling. It resets to `0` after a successful delivery.
* `enabled` - Whether the webhook is active. It is disabled automatically when `consecutive_failures` reaches 50.
* `auto_disabled_at` - When the webhook was disabled automatically, otherwise `null`

> [!NOTE]
>
> **Rate limit**: Each `/webhooks` endpoint allows **60 requests per minute** per API key. `POST /webhooks/{id}/test` allows **10 requests per minute**.

## Troubleshooting

### Common issues

**Webhooks configured but events don't fire**

This is the most common cause of "my webhook isn't working" reports. Per-webhook settings can be entirely correct while the account-level master switch is off, silently skipping every event.

* Confirm the [master switch](#two-levels-of-enablement) is on for the right scope: company-level webhooks need the company's switch on, workspace-level webhooks need that workspace's switch on.
* Don't trust a passing test as proof - `POST /webhooks/{id}/test` bypasses the master switch, so it can succeed while live events don't fire.
* Check `consecutive_failures` on the webhook - if it reads `0` and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
* If you can't find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from **Settings > Webhooks**.

**401 Unauthorized / Invalid signature**

* Verify you're using the correct signing secret
* Check that you're hashing the raw request body (not parsed JSON)
* Ensure you're using HMAC SHA-256, not other hash algorithms

**Timeouts / 504 errors**

* Respond with 200 immediately, process asynchronously
* Check your endpoint responds within 5 seconds
* Use background jobs/queues for heavy processing

**Duplicate events**

* Implement idempotency using the event `id`
* Store processed event IDs in your database

**Webhook auto-disabled**

* Check `consecutive_failures` and recent events in the webhook event log in the dashboard
* Fix endpoint issues, then re-enable webhook via API or dashboard

### Testing webhooks locally

Use a tunnel service like ngrok for local development:

```bash theme={null}
# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma
```

## Production checklist

* Verify HMAC signatures on all webhook requests
* Handle signature rotation (check both `X-Firma-Signature` and `X-Firma-Signature-Old`)
* Respond with 200 within 5 seconds
* Process events asynchronously (queues/background jobs)
* Implement idempotency using the event `id`
* Store signing secret securely (env var or secrets manager)
* Monitor `consecutive_failures` metric via GET webhook endpoint
* Set up alerts for webhook failures
* Log all webhook events for debugging
* Test with all subscribed event types
* Stay within rate limits (See [Rate Limit Guide](/guides/rate-limits))

## Next steps

* [Create a webhook](../api-reference/v01.15.00/webhooks/create-webhook) via API
* [Test your webhook](../api-reference/v01.15.00/webhooks/test-a-webhook) before going live
* [Update webhook settings](../api-reference/v01.15.00/webhooks/update-webhook) as needed


# White Labeling
Source: https://docs.firma.dev/guides/white-labeling

Configure custom branding, email domains, email templates, and embedded experiences to create a fully branded signing experience for your customers.

Firma provides comprehensive white-labeling capabilities that let you create a fully branded e-signature experience. From custom logos and color themes to embedded interfaces, you can ensure your customers interact with your brand throughout the entire signing process.

## Overview

White labeling in Firma involves several components:

1. **Custom branding** - Upload logos, set color themes, and hide Firma branding entirely
2. **Custom signer terms** - Require signers to accept your own terms of service
3. **Signing button labels** - Customize the text on signing buttons per language
4. **Custom email domains** - Send signing request emails from your own domain
5. **Custom email sender address** - Control the "from" address on all outgoing emails
6. **Custom email templates** - Personalize the content and branding of signing notification emails
7. **Disable Firma emails** - Turn off automatic emails per signing request and send your own
8. **Embedded experiences** - Embed signing and template editors directly in your app

> [!NOTE]
>
> All API examples on this page pass your API key directly in the `Authorization` header. The `Bearer` prefix is optional - both `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` work.

***

## Custom branding

Customize logos, colors, and branding visibility at both the company and workspace level. Workspace settings override company settings, letting you create distinct branded experiences for each of your customers.

### Company logo

Upload a logo for your entire Firma account. This logo appears in signing emails and the signing experience.

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"
```

**Requirements:**

* Format: PNG or JPEG only
* Max size: 2 MB

To remove the company logo:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace logo

Override the company logo for a specific workspace:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"
```

To remove a workspace logo (falls back to the company logo):

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"
```

### Color theming

Customize the color palette of the signing experience using hex color values. Colors can be set at both the company and workspace level.

| Color Setting | Description | Firma Default |
| - | - | - |
| `color_primary` | Primary accent color (buttons, links) | `#c285ff` |
| `color_primary_fg` | Text color on primary elements | `#ffffff` |
| `color_background` | Page background | `#1c1c21` |
| `color_foreground` | Primary text color | `#ffffff` |
| `color_card` | Card/panel background | `#22222a` |
| `color_border` | Border color | `#3b3b3b` |
| `color_accent` | Secondary accent color | `#34eeff` |
| `color_accent_fg` | Text color on accent elements | `#000000` |
| `color_canvas` | Document canvas/viewer background | `#0f1419` |
| `color_muted` | Muted/subtle background areas | `#22222a` |
| `color_muted_fg` | Text color on muted areas | `#b8b8b8` |

**Set company-level colors:**

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'
```

**Set workspace-level colors** (overrides company colors for this workspace):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'
```

Colors must be 6-digit hex values (e.g., `#0066cc`). Set a color to `null` to clear it and fall back to the next level in the hierarchy.

### Hide Firma branding

Strip Firma's support contact line from emails by enabling `show_custom_branding_only` at the company level. This setting does not change the signing page:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'
```

### Additional display settings

Fine-tune the signing experience with these settings, available at both company and workspace level:

| Setting | Description | Default |
| - | - | - |
| `show_signature_frame` | Show the signature drawing frame/border | `true` |
| `show_partial_watermark` | Show a watermark on partially-signed documents | `false` |
| `show_qr_code` | Show a QR code on the signing page and make `{{signing_qr_code}}` available to invitation emails | `true` |
| `require_otp_verification` | Require email OTP verification before signing | `false` |
| `require_terms_acceptance` | Require signers to accept terms before signing | `true` |
| `disable_guided_navigation` | Disable step-by-step guided field navigation | `false` |
| `allow_presigning_download` | Allow signers to download the document before signing | `false` |
| `allow_decline` | Show the Decline to Sign button; when `false`, signers and approvers cannot decline | `true` |
| `show_save_for_later` | Show the Save & Finish Later button | `true` |

At the workspace level, set these to `null` to inherit the company-level setting.

### Settings hierarchy

Branding settings follow a cascading hierarchy:

1. **Workspace setting** (highest priority)
2. **Company setting**
3. **Firma default** (lowest priority)

This lets you set company-wide defaults and override them per workspace. At the workspace level, setting a value to `null` means "inherit from company."

See the [Workspace Settings API Reference](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) for the full list of configurable settings.

***

## Custom signer terms

Require signers to accept your own terms of service or legal agreement before signing. Terms are configured per language and follow the same company/workspace cascade as other settings.

### How it works

When `require_terms_acceptance` is enabled (the default), signers see a terms acceptance checkbox before they can sign. You can customize the statement text and optionally link to a full terms document.

`require_terms_acceptance` follows the same cascade as other branding settings: **workspace setting → company setting → Firma default**. The Firma default is `true` (enabled), so terms acceptance is ON for every document unless you explicitly disable it at the company or workspace level.

Terms are stored per language so signers see terms in their workspace's language, falling back through the cascade:

1. **Workspace terms** for the signer's language (highest priority)
2. **Company terms** for the signer's language
3. **Workspace terms** for the workspace's configured language
4. **Company terms** for the company's configured language
5. **Firma default terms** (lowest priority)

> [!NOTE]
>
> Terms acceptance is tracked per signer, per signing request - not per signer email address. A signer who accepts terms on one document must accept them again on the next document; there is no cross-document "accept once" state.

### Set company-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'
```

### Set workspace-level terms

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'
```

**Fields:**

* `statement_text` (required): HTML text shown next to the acceptance checkbox. Basic HTML tags are allowed (`<a>`, `<b>`, `<i>`, `<br>`).
* `terms_url` (optional): URL to the full terms document.

### List terms

Retrieve all configured terms for a company or workspace:

```bash theme={null}
# Company terms
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Workspace terms
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"
```

### Delete terms

Remove custom terms for a specific language to fall back to the next level in the cascade:

```bash theme={null}
# Delete company terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Delete workspace terms for English
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"
```

### Disable terms acceptance

`require_terms_acceptance` can be turned off for your entire account or for a single workspace.

**Disable for your entire account** (all workspaces, unless a workspace overrides it):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

**Disable for a single workspace** (overrides the company setting for that workspace only):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'
```

Set `require_terms_acceptance` to `null` at the workspace level to clear the override and inherit the company setting again.

> [!NOTE]
>
> Workspace settings stored on the workspace can be changed only by an Owner. If this toggle shows a permission error, ask an Owner to update it.

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

See the [Signer Terms API Reference](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) for complete endpoint documentation.

***

## Custom signing button labels

Customize the text on signing buttons per workspace and per language. This lets you match the button labels to your product's terminology or localization.

### Set button label overrides

Button labels are set as a JSONB object on workspace settings, keyed by language and then by button key:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "common.finish": "Complete Signing",
        "signing.nextRequiredField": "Continue",
        "signing.saveAndFinishLater": "Save for Later"
      },
      "es": {
        "common.finish": "Completar firma",
        "signing.nextRequiredField": "Continuar",
        "signing.saveAndFinishLater": "Guardar para después"
      }
    }
  }'
```

### Clear button label overrides

Set to `null` to revert to Firma's default button labels:

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'
```

**Validation:**

* Each label must be a string - values over 200 characters are silently truncated
* Language keys are strings (max 10 characters, not validated against the supported-language list)
* HTML tags and control characters are stripped automatically

> [!NOTE]
>
> Button label overrides are a workspace-level setting only. There is no company-level override.

***

## Custom email domains

By default, signing request emails are sent from Firma's domain. With custom email domains, emails appear to come directly from your company or your customers' companies.

### Account-level (company) email domains

Set up a custom email domain for your entire Firma account. All workspaces will use this domain by default unless overridden.

#### Step 1: Add your domain

Use the API to add a custom email domain:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'
```

**Response (201 Created)**:

```json theme={null}
{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}
```

#### Step 2: Add TXT verification record

Add the verification TXT record to your DNS:

| Type | Name | Value |
| - | - | - |
| TXT | `_firma-verification.acme.com` | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |

> [!NOTE]
>
> DNS propagation typically takes a few minutes but can take up to 48 hours.

#### Step 3: Verify domain ownership

Once the TXT record is added, verify ownership:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}
```

#### Step 4: Finalize domain setup

After ownership is verified, finalize the domain to receive email-sending DNS records:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"
```

**Response**:

```json theme={null}
{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}
```

#### Step 5: Add DNS records

Add all three DNS records to your domain:

| Type | Name | Value |
| - | - | - |
| TXT | `@` | `v=spf1 include:amazonses.com ~all` |
| CNAME | `resend._domainkey` | `resend._domainkey.amazonses.com` |
| TXT | `_dmarc` | `v=DMARC1; p=none;` |

#### Step 6: Verify DNS records

Once DNS records are added, verify them:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"
```

**Response (all verified)**:

```json theme={null}
{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}
```

#### Step 7: Set as primary domain (optional)

If you have multiple domains, set one as the default:

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"
```

### Workspace-level email domains

For multi-tenant SaaS applications, you can configure different email domains per workspace. Workspace domains override the company-level domain.

The workflow is identical to company domains, but uses workspace-scoped endpoints:

| Action | Endpoint |
| - | - |
| List domains | `GET /workspace/{workspace_id}/domains` |
| Add domain | `POST /workspace/{workspace_id}/domains` |
| Get domain | `GET /workspace/{workspace_id}/domains/{id}` |
| Delete domain | `DELETE /workspace/{workspace_id}/domains/{id}` |
| Verify ownership | `POST /workspace/{workspace_id}/domains/{id}/verify-ownership` |
| Finalize setup | `POST /workspace/{workspace_id}/domains/{id}/finalize` |
| Verify DNS | `POST /workspace/{workspace_id}/domains/{id}/verify-dns` |
| Set primary | `POST /workspace/{workspace_id}/domains/{id}/set-primary` |

**Example: Add workspace domain**

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'
```

See the [Email Domains API Reference](/api-reference/v01.27.00/email-domains/list-company-domains) for complete endpoint documentation, or [Custom Domains](/guides/custom-domains) for DNS record details, Resend conflict resolution, and verification state troubleshooting.

***

## Custom email sender address

Control the "from" address on all outgoing emails by combining a custom domain with a custom local part.

### How email addresses are resolved

When Firma sends an email, the sender address is built from three components:

```
{sender_name} <{local_part}@{domain}>
```

Each component is resolved through a fallback chain:

**Domain resolution:**

1. Workspace verified domain (primary preferred)
2. Company verified domain
3. `updates.firma.dev` (default)

**Local part resolution** (only applies when using a custom domain):

1. Workspace `email_local_part` setting
2. Company `email_local_part` setting
3. `support` (default)

**Sender name** is the workspace name (falling back to the company name if the workspace has no name set).

For example, if your workspace is named "Acme Legal" and you set `email_local_part` to `noreply` with a verified domain `sign.acmecorp.com`, emails will be sent from:

```
Acme Legal <noreply@sign.acmecorp.com>
```

### Setting the email local part

**Company level** (default for all workspaces):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'
```

**Workspace level** (overrides company setting):

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'
```

**Validation rules:**

* 1-64 characters, lowercase letters, numbers, dots, underscores, and hyphens
* Must start and end with a letter or number
* No consecutive dots
* Reserved values (`postmaster`, `abuse`, `mailer-daemon`) are not allowed

Set to `null` at the workspace level to inherit from the company setting.

***

## Custom email templates

Customize the notification emails Firma sends on your behalf so they match your brand voice and style. You can set templates at both the company and workspace level, with workspace templates overriding company defaults.

### Customizable email types

| Email Type | When Sent |
| - | - |
| `signing_invite` | When a signing request is sent to a recipient |
| `next_signer` | When it's the next signer's turn in a signing order |
| `resend_notification` | When the sender manually resends a signing invitation |
| `reminder_default` | When an automatic reminder is sent for a pending signature |
| `signing_expired` | When a signing request expires |
| `signing_cancelled` | When a signing request is cancelled |
| `signing_declined` | When a signer declines (sent to other signers) |
| `signing_declined_admin` | When a signer declines (sent to the sender, includes decline reason) |
| `signing_completed` | When all signers have completed signing |
| `signer_identity_changed` | When a signer changes their name during signing |

### Available placeholders

Templates support HTML bodies with dynamic placeholders using `{{placeholder}}` syntax.

**Signer placeholders:**

| Placeholder | Description |
| - | - |
| `{{signer_first_name}}` | Signer's first name |
| `{{signer_last_name}}` | Signer's last name |
| `{{signer_name}}` | Signer's full name |
| `{{signer_email}}` | Signer's email address |
| `{{signer_title}}` | Signer's job title |
| `{{signer_company}}` | Signer's company name |

**Document placeholders:**

| Placeholder | Description |
| - | - |
| `{{signing_request_name}}` | Name of the signing request |
| `{{signing_link}}` | URL for the signer to sign |
| `{{expiration_date}}` | When the signing request expires |
| `{{download_link}}` | Link to download the signed document |
| `{{decliner_name}}` | Name of the signer who declined |
| `{{decline_reason}}` | Reason provided when declining |
| `{{signing_qr_code}}` | QR code image linking to the signing page |

**Team placeholders:**

| Placeholder | Description |
| - | - |
| `{{team_name}}` | Workspace/team name |
| `{{team_email}}` | Workspace contact email |
| `{{company_name}}` | Company name |
| `{{company_logo}}` | Company logo image |

You can also retrieve this list programmatically:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"
```

### View default templates

Retrieve Firma's built-in default templates for any supported language to use as a starting point:

```bash theme={null}
curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"
```

Supported languages: `en`, `es`, `it`, `pt`, `fr`, `de`, `el`, `ru`, `pl`, `cs`, `sv`, `nl`, `ro`, `nb`, `ca`.

### Set a workspace email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'
```

**Validation:**

* `subject`: required, max 500 characters
* `body`: required, max 50,000 characters

### Set a company email template

```bash theme={null}
curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'
```

### Delete a custom template

Remove a custom template to revert to the next level in the hierarchy:

```bash theme={null}
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"
```

### Template hierarchy

Email templates follow a cascading hierarchy:

1. **Workspace template** (highest priority)
2. **Company template**
3. **Built-in default** for the workspace's language (lowest priority)

This lets you set a company-wide branded template and override it for specific workspaces when needed. Deleting a template at any level causes it to fall back to the next level.

> [!WARNING]
>
> A warning is returned if a template body does not contain the `{{signing_link}}` placeholder, since recipients need a link to access the signing flow.

See the [Email Templates API Reference](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) for complete endpoint documentation.

***

## Disabling Firma emails

For complete control over customer communications, you can disable Firma's automatic emails per signing request. This allows you to:

* Send signing request links through your own email system
* Integrate with your existing notification workflows
* Customize email timing and follow-up sequences
* Use your own email delivery infrastructure

### Email settings on signing requests

Each signing request has settings that control which emails are sent:

| Setting | Description | Default |
| - | - | - |
| `send_signing_email` | Send signing request notification emails to signers | `true` |
| `send_finish_email` | Send completion email when all signers finish | `true` |
| `send_expiration_email` | Send expiration notification when request expires | `true` |
| `send_cancellation_email` | Send cancellation notification when request is cancelled | `true` |

### Create signing request with emails disabled

```bash theme={null}
curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'
```

### Get signing URLs for manual distribution

When emails are disabled, retrieve the signing URLs from the API and send them through your own channels:

```js theme={null}
// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}
```

***

## Embedded experiences

The most powerful white-labeling feature is embedding Firma's interfaces directly in your application. This removes all Firma branding and creates a seamless experience within your product.

### Embeddable signing

Embed the signing flow so recipients sign documents without leaving your app:

```html theme={null}
<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>
```

[Embeddable Signing Guide](/guides/embeddable-signing) - Full implementation details

### Embeddable template editor

Let users create and edit templates within your app using JWT authentication. The editor loads via a script tag and mounts into a container element via Shadow DOM - not an iframe:

```html theme={null}
<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>
```

[Embeddable Template Editor Guide](/guides/embeddable-template-editor) - JWT generation, events, and full implementation

### Embeddable signing request editor

Same pattern - script tag + constructor, not an iframe:

```html theme={null}
<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>
```

[Embeddable Signing Request Editor Guide](/guides/embeddable-signing-request-editor) - full implementation guide

***

## Complete white-label setup

Here's a complete example of setting up a fully white-labeled workspace for a customer:

### 1. Create the workspace

```js theme={null}
const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)
```

### 2. Upload a logo

```js theme={null}
const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)
```

### 3. Configure branding

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)
```

### 4. Hide Firma branding (company-level)

```js theme={null}
await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)
```

### 5. Set up custom email domain (optional)

```js theme={null}
// Add domain
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// User adds TXT record to DNS...
// Verify ownership
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finalize (returns SPF, DKIM, DMARC records)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// User adds DNS records...
// Verify DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Set as primary
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)
```

### 6. Customize email templates (optional)

```js theme={null}
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)
```

### 7. Embed the experiences

```jsx theme={null}
function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Your branded header */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Embedded Firma signing */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Your branded footer */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}
```

***

## Best practices

### Branding

* Use a consistent color palette across logos, email templates, and embedded experiences
* Upload logos in PNG format with a transparent background for best results
* Enable `show_custom_branding_only` to strip Firma's support contact line from emails; it does not change the signing page
* Set company-level branding as a baseline, then override per workspace where needed
* Test the full signing flow from your customers' perspective

### Email domain configuration

* Use a subdomain (e.g., `sign.yourcompany.com`) rather than your main domain
* Set up all DNS records (SPF, DKIM, DMARC) for optimal deliverability
* Monitor email bounce rates and adjust as needed
* Test email delivery before going live with customers

### Email templates

* Use the [defaults endpoint](#view-default-templates) to see Firma's built-in templates as a starting point
* Always include `{{signing_link}}` in invite and reminder templates
* Set a company-level template as a branded baseline, then override per workspace when needed
* Use `{{company_logo}}` in templates to include the workspace or company logo

### Security

* Always generate JWT tokens on your backend
* Never expose API keys in client-side code
* Token expiration is fixed server-side: 24 hours for template editor tokens, 7 days for signing-request tokens - not configurable by the caller
* Validate postMessage origins when handling iframe events

***

## Troubleshooting

### Domain ownership verification failed

**Possible causes**:

* DNS records not propagated (wait up to 48 hours)
* Incorrect TXT record name or value
* TXT record added to wrong zone

**Solution**: Check your DNS configuration matches the `verification_instructions` returned when adding the domain

### DNS records not verifying

**Possible causes**:

* Records not propagated yet
* Incorrect record values
* Missing records

**Solution**: Call `GET /company/domains/{id}` or `verify-dns` to see which specific records are pending

### Signing iframe not loading

**Possible causes**:

* Invalid signing request user ID
* Expired or cancelled signing request
* Content Security Policy blocking iframe

**Solution**: Verify signing request status and check browser console for CSP errors

### JWT token expired

**Possible causes**:

* Token TTL too short for use case
* Clock skew between servers

**Solution**: Generate tokens with appropriate expiration, consider refreshing tokens proactively

### Colors not applying

**Possible causes**:

* Invalid hex format (must be 6-digit, e.g., `#0066cc`, not 3-digit `#06c`)
* Setting applied at company level but workspace has its own override

**Solution**: Check workspace settings first, then company settings. Use `null` at the workspace level to clear an override.

***

## Related guides

* [Embeddable Signing](/guides/embeddable-signing) - Embed the signing experience in your app
* [Embeddable Template Editor](/guides/embeddable-template-editor) - Let users edit templates with JWT auth
* [Embeddable Signing Request Editor](/guides/embeddable-signing-request-editor) - Configure signing requests in your UI
* [Creating Workspaces](/guides/creating-workspaces) - Set up isolated environments for customers
* [Webhooks](/guides/webhooks) - Track signing events in real-time


# Workspace Settings
Source: https://docs.firma.dev/guides/workspace-settings

Configure workspace-level settings including email templates, team information, and timezone preferences.

Workspace settings allow you to customize email templates, team contact information, and timezone preferences at the workspace level. These settings apply to all signing requests and templates within the workspace.

## Use cases

* **Custom email branding**: Personalize email headers and body text for signing request invitations
* **Team contact info**: Set a team email for recipient support questions
* **Timezone management**: Configure timezone for date/time displays and reminders
* **Multi-tenant applications**: Separate settings per workspace for white-label solutions

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## Get workspace settings

Retrieve current workspace settings including email templates, team email, and timezone configuration.

### Endpoint

```
GET /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Example - cURL

```bash theme={null}
curl -X GET "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200 OK)

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience. If you have any questions, contact our team.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

> [!NOTE]
>
> The response includes additional fields beyond email settings - `show_qr_code`, `require_otp_verification`, `require_terms_acceptance`, `allow_presigning_download`, color settings, `signing_button_label_overrides`, completion page settings, and more. This guide focuses on the email template and branding subset. See the [API reference](/api-reference/v01.33.00/workspace-settings/get-workspace-settings) for the full response schema.

### Rate limit headers

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Update workspace settings

Update workspace settings. You can update one or more fields - only provided fields will be updated.

### Endpoint

```
PUT /workspace/{workspace_id}/settings
```

### Parameters

* `workspace_id` (string, required) - UUID of the workspace

### Request body

All fields are optional - only include fields you want to update:

```json theme={null}
{
  "signing_request_email_header": "You've been invited to sign a document",
  "signing_request_email_body": "Please review and sign the document at your earliest convenience.",
  "team_email": "support@yourcompany.com",
  "timezone": "America/New_York"
}
```

### Field descriptions

* `signing_request_email_header` (string, optional) - Custom header text for signing emails (max 500 characters)
* `signing_request_email_body` (string, optional) - Custom body text for signing emails (max 50000 characters)
* `team_email` (string, optional) - Valid email address for recipient support
* `timezone` (string, optional) - IANA timezone identifier

### Example - cURL

```bash theme={null}
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspace/123e4567-e89b-12d3-a456-426614174000/settings" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_request_email_header": "Action Required: Sign Your Agreement",
    "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
    "team_email": "support@acmecorp.com",
    "timezone": "America/Los_Angeles"
  }'
```

### Response (200 OK)

Returns the updated workspace settings:

```json theme={null}
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "signing_request_email_header": "Action Required: Sign Your Agreement",
  "signing_request_email_body": "Hello! We need your signature on an important document. Please click the link below to review and sign. Contact us at support@acmecorp.com if you have questions.",
  "team_email": "support@acmecorp.com",
  "timezone": "America/Los_Angeles"
}
```

### Rate limit headers

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z
```

***

## Implementation examples

### Node.js (Express) - Get settings

```js theme={null}
import express from 'express'
import fetch from 'node-fetch'

const app = express()
const FIRMA_API_BASE = process.env.FIRMA_API_BASE || 'https://api.firma.dev/functions/v1/signing-request-api'
const API_KEY = process.env.FIRMA_API_KEY

app.get('/api/workspace/:workspaceId/settings', async (req, res) => {
  const { workspaceId } = req.params
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to get workspace settings:', error)
    res.status(500).json({ error: 'Failed to retrieve settings' })
  }
})

app.listen(3000)
```

### Node.js (Express) - Update settings

```js theme={null}
app.put('/api/workspace/:workspaceId/settings', express.json(), async (req, res) => {
  const { workspaceId } = req.params
  const { signing_request_email_header, signing_request_email_body, team_email, timezone } = req.body
  
  // Validate input
  if (team_email && !isValidEmail(team_email)) {
    return res.status(400).json({ error: 'Invalid email format' })
  }
  
  try {
    const response = await fetch(
      `${FIRMA_API_BASE}/workspace/${workspaceId}/settings`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          signing_request_email_header,
          signing_request_email_body,
          team_email,
          timezone
        })
      }
    )
    
    if (!response.ok) {
      const error = await response.text()
      return res.status(response.status).json({ error })
    }
    
    const settings = await response.json()
    res.json(settings)
  } catch (error) {
    console.error('Failed to update workspace settings:', error)
    res.status(500).json({ error: 'Failed to update settings' })
  }
})

function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}
```

### Python (Flask) - Get settings

```py theme={null}
from flask import Flask, jsonify
import os
import requests

app = Flask(__name__)

FIRMA_API_BASE = os.getenv('FIRMA_API_BASE', 'https://api.firma.dev/functions/v1/signing-request-api')
API_KEY = os.getenv('FIRMA_API_KEY')

@app.route('/api/workspace/<workspace_id>/settings', methods=['GET'])
def get_workspace_settings(workspace_id):
    try:
        response = requests.get(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}'
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to retrieve settings'}), 500

if __name__ == '__main__':
    app.run(port=3000)
```

### Python (Flask) - Update settings

```py theme={null}
from flask import request
import re

@app.route('/api/workspace/<workspace_id>/settings', methods=['PUT'])
def update_workspace_settings(workspace_id):
    data = request.json
    
    # Validate email if provided
    if 'team_email' in data:
        if not re.match(r'^[^\s@]+@[^\s@]+\.[^\s@]+$', data['team_email']):
            return jsonify({'error': 'Invalid email format'}), 400
    
    try:
        response = requests.put(
            f'{FIRMA_API_BASE}/workspace/{workspace_id}/settings',
            headers={
                'Authorization': f'Bearer {API_KEY}',
                'Content-Type': 'application/json'
            },
            json={
                'signing_request_email_header': data.get('signing_request_email_header'),
                'signing_request_email_body': data.get('signing_request_email_body'),
                'team_email': data.get('team_email'),
                'timezone': data.get('timezone')
            }
        )
        response.raise_for_status()
        return jsonify(response.json())
    except requests.exceptions.RequestException as e:
        return jsonify({'error': 'Failed to update settings'}), 500
```

### React - Settings management component

```jsx theme={null}
import { useState, useEffect } from 'react'

function WorkspaceSettings({ workspaceId }) {
  const [settings, setSettings] = useState(null)
  const [loading, setLoading] = useState(true)
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState(null)
  
  // Load current settings
  useEffect(() => {
    async function loadSettings() {
      try {
        const response = await fetch(`/api/workspace/${workspaceId}/settings`)
        if (!response.ok) throw new Error('Failed to load settings')
        const data = await response.json()
        setSettings(data)
      } catch (err) {
        setError(err.message)
      } finally {
        setLoading(false)
      }
    }
    loadSettings()
  }, [workspaceId])
  
  // Update settings
  async function handleSave(updatedSettings) {
    setSaving(true)
    setError(null)
    
    try {
      const response = await fetch(`/api/workspace/${workspaceId}/settings`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(updatedSettings)
      })
      
      if (!response.ok) throw new Error('Failed to save settings')
      
      const data = await response.json()
      setSettings(data)
    } catch (err) {
      setError(err.message)
    } finally {
      setSaving(false)
    }
  }
  
  if (loading) return <div>Loading settings...</div>
  if (error) return <div>Error: {error}</div>
  
  return (
    <div>
      <h2>Workspace Settings</h2>
      
      <form onSubmit={(e) => {
        e.preventDefault()
        const formData = new FormData(e.target)
        handleSave({
          email_header: formData.get('email_header'),
          email_body: formData.get('email_body'),
          team_email: formData.get('team_email'),
          timezone: formData.get('timezone')
        })
      }}>
        <div>
          <label>Email Header</label>
          <input
            name="signing_request_email_header"
            defaultValue={settings.email_header}
            maxLength={500}
          />
        </div>
        
        <div>
          <label>Email Body</label>
          <textarea
            name="signing_request_email_body"
            defaultValue={settings.email_body}
            maxLength={50000}
            rows={5}
          />
        </div>
        
        <div>
          <label>Team Email</label>
          <input
            name="team_email"
            type="email"
            defaultValue={settings.team_email}
          />
        </div>
        
        <div>
          <label>Timezone</label>
          <select name="timezone" defaultValue={settings.timezone}>
            <option value="America/New_York">Eastern Time</option>
            <option value="America/Chicago">Central Time</option>
            <option value="America/Denver">Mountain Time</option>
            <option value="America/Los_Angeles">Pacific Time</option>
            <option value="Europe/London">London</option>
            <option value="Europe/Paris">Paris</option>
            <option value="Asia/Tokyo">Tokyo</option>
            {/* Add more timezones as needed */}
          </select>
        </div>
        
        <button type="submit" disabled={saving}>
          {saving ? 'Saving...' : 'Save Settings'}
        </button>
      </form>
    </div>
  )
}
```

***

## Email template customization

Firma supports two layers of email customization that share the same placeholder engine: the `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint (which apply to the signing invitation and next-signer emails, including manual resends of either), and a richer per-type Email Templates editor in the workspace's Settings page, which lets you customize the subject and body independently for each email type - invitation, next signer, expiration, cancellation, decline, completion, and identity-change notifications.

### Template variable reference

| Variable | Resolves to | Category |
| - | - | - |
| `{{signer_first_name}}` | Signer's first name | Signer |
| `{{signer_last_name}}` | Signer's last name | Signer |
| `{{signer_name}}` | Signer's full name | Signer |
| `{{signer_email}}` | Signer's email address | Signer |
| `{{signer_title}}` | Signer's job title (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signer_company}}` | Signer's company name (only populated in reminder emails - resolves to empty in all other email types) | Signer |
| `{{signing_request_name}}` | Name of the signing request | Document |
| `{{signing_link}}` | URL for the signer to open and sign | Document |
| `{{expiration_date}}` | When the signing request expires | Document |
| `{{download_link}}` | Link to download the signed document | Document |
| `{{decliner_name}}` | Name of the signer who declined | Document |
| `{{decline_reason}}` | Reason given when declining | Document |
| `{{team_name}}` / `{{workspace_name}}` | Workspace name (aliases - same value) | Team |
| `{{team_email}}` / `{{workspace_email}}` | Workspace contact email (aliases - same value) | Team |
| `{{company_name}}` | Company name | Team |
| `{{company_logo}}` | `<img>` tag for the workspace or company logo | Branding |
| `{{signing_qr_code}}` | `<img>` tag for a QR code linking to the signing page | Branding |

> [!NOTE]
>
> Placeholders are case-insensitive and also accept the legacy `[bracket]` syntax (for example `[signer_name]`) alongside `{{curly}}` syntax. A placeholder with no value for a given email simply resolves to nothing - templates never show a raw `{{missing_variable}}`.

### Variable availability by email type

Signer, document, team, and company variables resolve for every email type. Three variables are the exception:

| Variable | Available in |
| - | - |
| `{{signing_qr_code}}` | Signing invitation and next-signer emails only |
| `{{decliner_name}}` / `{{decline_reason}}` | Decline notification emails only (both the signer-facing and admin-facing versions) |
| `{{download_link}}` | Completion emails only |

> [!NOTE]
>
> The `signing_request_email_header` / `signing_request_email_body` fields on this settings endpoint only affect the invitation and next-signer emails. To customize expiration, cancellation, decline, completion, or identity-change emails, use the per-type Email Templates editor in the workspace's Settings page.

### Company logo (`{{company_logo}}`)

`{{company_logo}}` resolves through a fallback chain:

1. **Workspace logo** - used if the workspace has its own logo uploaded (rendered with the workspace name as the image `alt` text).
2. **Company logo** - otherwise, falls back to the parent company's logo.
3. **Hidden** - if neither is set, the placeholder resolves to nothing; no broken image is rendered.

The logo image is served through a public logo proxy and constrained to `max-width: 200px; max-height: 120px`. The height cap prevents unusually tall logos from pushing the rest of the email below the fold.

### QR code in emails (`{{signing_qr_code}}`)

> [!WARNING]
>
> Email QR codes render as **PNG**, not SVG. Gmail strips `<img>` tags pointing at SVG entirely, and Outlook's Word-based rendering engine won't display them either - PNG is the format that renders reliably across email clients.

`{{signing_qr_code}}` is only populated on signing invitation and next-signer emails. It lets a recipient scan the code to continue signing on another device instead of clicking a link. Whether it's shown is controlled by a `show_qr_code` setting that cascades:

1. Signing request-level setting (if explicitly set)
2. Workspace-level setting - `show_qr_code` on this settings endpoint
3. Company-level default

Set `show_qr_code` to `true` or `false` at the workspace level via `PUT /workspace/{workspace_id}/settings`, or leave it unset (`null`) to inherit the company default.

### Workspace email (`{{team_email}}` / `{{workspace_email}}`)

`team_email` is a workspace-level field, configured on this settings endpoint (or from the workspace's Settings page, under **Team Contact Email**). If left unset, it falls back to Firma's support address.

> [!NOTE]
>
> `team_email` is a display value only - it's substituted wherever `{{team_email}}` or `{{workspace_email}}` appears in a template. It is **not** used as the email's `Reply-To` address; replies from recipients go to Firma's sending address, not to `team_email`.

`team_email` also has a second, unrelated role: for identity-change notifications, it's the actual recipient. Firma emails your team at this address when a signer changes their name mid-flow, falling back to the account owner's email if `team_email` isn't set.

### Best practices

**Email header** (max 500 characters):

* Keep it concise and action-oriented
* Clearly state the purpose ("Sign your agreement", "Review document")
* Avoid generic text like "You have a notification"

**Email body** (max 50000 characters):

* Explain what the recipient needs to do
* Include support contact information
* Set expectations (urgency, deadline if applicable)
* Keep tone professional but friendly

### Example templates

**Professional services**:

```
Header: "Action Required: Review and Sign Your Contract"
Body: "Thank you for choosing our services. Please review and sign the attached contract at your earliest convenience. If you have any questions or concerns, please contact us at contracts@company.com or call (555) 123-4567."
```

**Real estate**:

```
Header: "Your Property Documents Are Ready to Sign"
Body: "Your documents are ready for electronic signature. Please review carefully before signing. Contact your agent at agent@realty.com if you need clarification on any terms."
```

**HR onboarding**:

```
Header: "Welcome to [Company]! Complete Your Onboarding Documents"
Body: "Welcome to the team! As part of your onboarding, please review and sign the attached documents. If you have questions, reach out to hr@company.com. We're excited to have you aboard!"
```

**Generic/flexible**:

```
Header: "Document Ready for Your Signature"
Body: "A document requires your signature. Please review the contents and sign electronically. Contact us at support@company.com with any questions."
```

***

## Supported timezones

Workspace settings support all IANA timezone identifiers. Common timezones:

### United States

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `America/Anchorage` - Alaska Time
* `Pacific/Honolulu` - Hawaii Time

### Europe

* `Europe/London` - GMT/BST
* `Europe/Paris` - Central European Time
* `Europe/Berlin` - Central European Time
* `Europe/Madrid` - Central European Time
* `Europe/Rome` - Central European Time

### Asia Pacific

* `Asia/Tokyo` - Japan Standard Time
* `Asia/Shanghai` - China Standard Time
* `Asia/Singapore` - Singapore Time
* `Asia/Dubai` - Gulf Standard Time
* `Australia/Sydney` - Australian Eastern Time

### Americas

* `America/Toronto` - Eastern Time (Canada)
* `America/Vancouver` - Pacific Time (Canada)
* `America/Mexico_City` - Central Time (Mexico)
* `America/Sao_Paulo` - Brasilia Time

[Full list of IANA timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

***

## Rate limiting

### Get workspace settings

* **Limit**: 200 requests per minute
* **Use case**: Frequent reads for dashboard displays
* **Recommendation**: Cache settings client-side for 5-10 minutes

### Update workspace settings

* **Limit**: 120 requests per minute
* **Use case**: Admin configuration changes
* **Recommendation**: Debounce updates in UI (wait 1-2 seconds after user stops typing)

### Rate limit headers

Every response includes:

```
X-RateLimit-Limit: 200          # Max requests per minute
X-RateLimit-Remaining: 195       # Remaining in current window
X-RateLimit-Reset: 2026-08-07T12:35:00.000Z    # Unix timestamp of reset
```

### Handling rate limits

If you exceed the limit:

```
429 Too Many Requests
```

**Best practices**:

* Implement client-side caching
* Debounce frequent updates
* Check `X-RateLimit-Remaining` before making requests
* Implement exponential backoff for retries

***

## Error responses

### 400 Bad Request - Validation error

Invalid input data (e.g., malformed email, invalid timezone):

```json theme={null}
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

### 403 Forbidden

You don't have access to this workspace (cross-company or insufficient permissions):

```json theme={null}
{
  "error": "Access denied",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

Workspace doesn't exist or has been deleted:

```json theme={null}
{
  "error": "Workspace not found",
  "code": "NOT_FOUND"
}
```

### 429 Too Many Requests

Rate limit exceeded:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 120,
    "window": "1m",
    "current_count": 121,
    "retry_after_seconds": 45
  }
}
```

Check the `X-RateLimit-Reset` header (ISO 8601 timestamp) for when you can retry.

***

## Multi-tenant best practices

For multi-tenant applications (multiple workspaces):

### 1. Cache settings per workspace

```js theme={null}
const settingsCache = new Map()
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getWorkspaceSettings(workspaceId) {
  const cached = settingsCache.get(workspaceId)
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.settings
  }
  
  const settings = await fetchWorkspaceSettings(workspaceId)
  settingsCache.set(workspaceId, {
    settings,
    timestamp: Date.now()
  })
  
  return settings
}
```

### 2. Validate workspace access

Always verify the authenticated user has access to the workspace:

```js theme={null}
async function updateSettings(userId, workspaceId, updates) {
  // Verify user has admin access to workspace
  const hasAccess = await checkWorkspaceAccess(userId, workspaceId, 'admin')
  if (!hasAccess) {
    throw new Error('Forbidden: Insufficient permissions')
  }
  
  // Update settings
  return await updateWorkspaceSettings(workspaceId, updates)
}
```

### 3. Audit logging

Log all settings changes for compliance:

```js theme={null}
async function updateWithAudit(workspaceId, userId, updates) {
  const oldSettings = await getWorkspaceSettings(workspaceId)
  const newSettings = await updateWorkspaceSettings(workspaceId, updates)
  
  // Log the change
  await auditLog.create({
    workspace_id: workspaceId,
    user_id: userId,
    action: 'workspace_settings_updated',
    changes: {
      old: oldSettings,
      new: newSettings
    },
    timestamp: new Date()
  })
  
  return newSettings
}
```

### 4. Default settings on workspace creation

Set sensible defaults when creating new workspaces:

```js theme={null}
async function createWorkspace(name, ownerId) {
  const workspace = await db.workspaces.create({ name, owner_id: ownerId })
  
  // Set default settings
  await updateWorkspaceSettings(workspace.id, {
    email_header: "You've been invited to sign a document",
    email_body: "Please review and sign the document at your earliest convenience.",
    team_email: "support@yourcompany.com",
    timezone: "America/New_York"
  })
  
  return workspace
}
```

***

## Troubleshooting

### Settings not applying to emails

**Symptom**: Updated settings don't appear in signing emails

**Possible causes**:

* Email template cache not cleared
* Wrong workspace ID used
* Updates didn't save (check API response)

**Solution**:

* Verify update was successful (check 200 response)
* Test with a new signing request (not existing draft)
* Check workspace ID matches signing request

### Invalid timezone error

**Symptom**: 400 error when setting timezone

**Solution**: Use IANA timezone identifiers (e.g., `America/New_York`). The API validates format only (letters, underscores, slashes) - abbreviations like `EST` pass validation but may not behave correctly for daylight saving transitions. Always use the full IANA zone name.

### Team email validation failure

**Symptom**: 400 error on team email update

**Solution**: Ensure valid email format (contains @ and domain)

### Rate limit exceeded

**Symptom**: 429 errors when updating settings

**Solution**:

* Implement debouncing on form inputs
* Cache settings client-side
* Wait for `X-RateLimit-Reset` before retrying

> [!NOTE]
>
> See the guide on [Rate Limits](/guides/rate-limits).

***

## API reference

For complete details on workspace operations, see:

### Workspace Management

* [List Workspaces](../api-reference/v01.15.00/workspaces/list-workspaces) - Get all workspaces (200 req/min)
* [Create Workspace](../api-reference/v01.15.00/workspaces/create-a-new-workspace) - Create new workspace (120 req/min)
* [Update Workspace](../api-reference/v01.15.00/workspaces/update-a-workspace) - Update workspace details (120 req/min)

### Workspace Settings

* [Get Workspace Settings](../api-reference/v01.15.00/workspace-settings/get-workspace-settings) - Retrieve current settings (200 req/min)
* [Update Workspace Settings](../api-reference/v01.15.00/workspace-settings/update-workspace-settings) - Update email templates and preferences (120 req/min)

### Related Endpoints

* [Generate JWT Token for Templates](../api-reference/v01.15.00/jwt-management/generate-jwt-token-for-embedding-templates) - For embedded template editor (120 req/min)
* [Create Template](../api-reference/v01.15.00/templates/create-template) - Create templates per workspace (120 req/min)
* [Create Signing Request](../api-reference/v01.15.00/signing-requests/create-signing-request) - Send documents with workspace branding (120 req/min)

***

## Next steps

* [Create workspaces](/guides/creating-workspaces) for multi-tenant applications
* [Send signing requests](/guides/sending-signing-request) with customized emails
* [Set up webhooks](/guides/webhooks) to track workspace activity
* [Embeddable template editor](/guides/embeddable-template-editor) with JWT authentication for embedded integrations